@fastagent-sh/fastagent 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the fastagent authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+<p align="center">
+  <a href="https://github.com/fastagent-sh/fastagent"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, on GitHub, in Telegram, or any channel." width="860"></a>
+</p>
+
+[![CI](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml/badge.svg)](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@fastagent-sh/fastagent.svg)](https://www.npmjs.com/package/@fastagent-sh/fastagent)
+[![license](https://img.shields.io/npm/l/@fastagent-sh/fastagent.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/@fastagent-sh/fastagent.svg)](https://nodejs.org)
+[![built with pi](https://img.shields.io/badge/built%20with-pi-0b7285.svg)](https://pi.dev)
+
+<p align="center">
+  <sub>Built on</sub>
+  <a href="https://pi.dev"><img src="https://pi.dev/logo-auto.svg" alt="pi" height="22" /></a>
+  <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.
+
+Leave the terminal. Become a real 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.
+
+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.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="fastagent dev boots an existing agent directory (AGENTS.md, skills/, tools/, channels/) into a live service; a GitHub pull_request.opened webhook arrives and the agent reviews PR #42 and posts inline comments." width="860">
+</p>
+
+## Why FastAgent
+
+Coding agents made it cheap to vibe useful agent directories. The hard part is the next step: local agents live in terminals, but real services receive webhooks, join Telegram, serve product users, and expose stable APIs.
+
+FastAgent is the missing bridge from local agent directory to real 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, 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.** Like Flask/FastAPI for agents: FastAgent never owns your framework. Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler — your auth, your database, your host.
+- **Deploy anywhere.** Run the directory directly — no build step; `fastagent deploy fly|railway` generates the host config + a runbook and hands off (`--run` drives the deploy to completion). The generated container also runs on other Docker hosts.
+
+Using a coding agent? Give it [`docs/ai-start.md`](docs/ai-start.md) for an AI-guided setup path.
+
+## Design philosophy
+
+FastAgent is built around a small serving contract, app-owned runtime concerns, typed boundaries, and composable adapters.
+
+- **Small serving core** — `invoke` decouples channels, agents, engines, and hosts.
+- **App-owned runtime** — no takeover of your auth, database, routes, or deployment.
+- **Typed edges** — typed tools, explicit events, boundary validation.
+- **Agent-native shape** — the directory is the deployable unit, and channels drive the same contract.
+
+Read [Design principles](docs/principles.md) for the full rationale.
+
+## What we didn't build
+
+FastAgent stays a small serving layer, so it never dictates your stack. Capabilities other agent frameworks bake into a platform, we leave to your app, your host, or the agent itself — composed in, not locked in.
+
+- **No platform to move to.** No dashboard, no control plane, no runtime you deploy *into* — run it locally, embed it in your app, or ship the directory to any host.
+- **No new format or DSL.** `AGENTS.md`, Agent Skills, TypeScript tools, HTTP/SSE — FastAgent consumes the standards you already use instead of a parallel ecosystem.
+- **No workflow engine.** The agent decides its own steps; for deterministic multi-step orchestration, call `invoke` from your own queue or workflow.
+- **No model or cloud lock-in.** The Agent Handler contract is engine-neutral, with pi as the reference implementation; another engine can implement the same `Agent` contract without changing channels.
+
+## Install
+
+```bash
+npm i -g @fastagent-sh/fastagent   # CLI: fastagent init/dev/start/...
+npm i @fastagent-sh/fastagent      # library API for embedding or code tools
+```
+
+Requires **Node >= 22.19** (the floor is inherited from the pi reference engine and `undici`), and also runs under **Bun** (smoke-tested in CI on Bun 1.3; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.
+
+## Quickstart
+
+```bash
+fastagent init my-agent
+cd my-agent
+fastagent dev
+```
+
+Then send a local test turn:
+
+```bash
+curl -N -X POST localhost:8787/invoke \
+  -H 'content-type: application/json' \
+  -d '{"session":"s1","text":"hello"}'
+```
+
+For production-style local serving:
+
+```bash
+fastagent start
+```
+
+There is no FastAgent build step: the directory is the agent.
+
+## Embed in an app
+
+```ts
+import { createInvokeHandler, createPiAgentFromDefinition } from "@fastagent-sh/fastagent";
+
+const { agent } = await createPiAgentFromDefinition("./agent", {
+  model: "openai-codex/gpt-5.5",
+});
+
+export const POST = createInvokeHandler(agent); // Fetch-shaped handler
+```
+
+No directory? Assemble from typed parts:
+
+```ts
+import { createPiAgent, defineTool, z } from "@fastagent-sh/fastagent";
+
+const lookupOrder = defineTool({
+  name: "lookup-order",
+  description: "Look up an order by id.",
+  input: z.object({ orderId: z.string() }),
+  async execute({ orderId }) {
+    return await db.find(orderId);
+  },
+});
+
+const agent = createPiAgent({
+  model: "openai-codex/gpt-5.5",
+  instructions: "You are a support assistant. Use lookup-order for order questions.",
+  tools: [lookupOrder],
+});
+```
+
+## Documentation
+
+| Document | Purpose |
+|---|---|
+| [docs/README.md](docs/README.md) | Documentation index |
+| [docs/quickstart.md](docs/quickstart.md) | Scaffold, run, add a tool, and start |
+| [docs/configuration.md](docs/configuration.md) | Configure model, auth, ports, sessions, tools, and channels |
+| [docs/principles.md](docs/principles.md) | Design choices, core primitives, and non-goals |
+| [docs/cli.md](docs/cli.md) | CLI reference |
+| [docs/embedding.md](docs/embedding.md) | Use FastAgent as a library inside your own app |
+| [docs/channels.md](docs/channels.md) | Add webhook/bot channels |
+| [docs/deploy.md](docs/deploy.md) | Ship the directory to Fly, Railway, or any Docker host |
+| [docs/github.md](docs/github.md) / [docs/telegram.md](docs/telegram.md) | First-party channel guides |
+| [docs/channel-development.md](docs/channel-development.md) | Build custom channel adapters |
+| [docs/api-reference.md](docs/api-reference.md) | Public TypeScript API reference |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common setup/runtime issues |
+| [docs/SPEC.md](docs/SPEC.md) | Agent Handler protocol v0.1 |
+| [docs/design/core.md](docs/design/core.md) | Maintainer architecture notes |
+
+## Public API surface & stability
+
+The root export intentionally contains the supported surface only.
+
+| Area | Examples | Stability |
+|---|---|---|
+| Contract | `Agent`, `AgentEvent`, `collect` | Stable within SPEC v0.1 |
+| Channels/host | `createInvokeHandler`, `nodeListener`, `serveNode`, `router`, `Routes` | Reference implementation, pre-1.0 |
+| pi assembly | `createPiAgentFromWorkspace`, `createPiAgentFromDefinition`, `createPiAgent` | Usable now, may tighten before 1.0 |
+| Tool/channel authoring | `defineTool`, `z`, `loadTools`, `loadChannels`, `ChannelModule` | Usable now, may tighten before 1.0 |
+| Injection ports | `PiSessionStore`, `inMemorySessionStore`, `jsonlSessionStore`, `Lease`, `Provider`, `createProvider` | Public because options reference them |
+| Not exported | L0 harness adapter, pi harness factory, prompt/config internals | Internal modules; no compatibility promise |
+
+Subpath exports:
+
+- `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel/host kit, schedules;
+- `@fastagent-sh/fastagent/pi` — the pi reference implementation;
+- `@fastagent-sh/fastagent/github` — GitHub webhook channel;
+- `@fastagent-sh/fastagent/telegram` — Telegram bot channel.
+
+## Repository layout
+
+```txt
+src/     the npm package: CLI, library API, reference implementation
+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.
+
+## Status
+
+FastAgent is pre-1.0. The stable design center is the Agent Handler contract in `docs/SPEC.md`; the package API may still tighten before 1.0. Notable changes are recorded in the [GitHub Releases](https://github.com/fastagent-sh/fastagent/releases).
+
+## Designed for more
+
+The neutral contract leaves room for capabilities that are not complete product features yet:
+
+- **Durable execution** — Telegram accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
+- **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
+- **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
+- **More reference bindings and channels** — pi is the reference implementation; another engine can implement the Agent contract, and community channels can use the channel kit.
+- **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
+
+See [Contributing](CONTRIBUTING.md) if one of these is the problem you want to work on.
+
+## Project
+
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Acknowledgements
+
+FastAgent stands on open source. The reference implementation is built on **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — its agent harness, multi-provider LLM API, and the interactive TUI that `fastagent chat` drives.
+
+It also depends on, and is grateful to, [zod](https://github.com/colinhacks/zod), [undici](https://github.com/nodejs/undici), [chokidar](https://github.com/paulmillr/chokidar), [giget](https://github.com/unjs/giget), [@clack/prompts](https://github.com/bombshell-dev/clack), [ignore](https://github.com/kaelzhang/node-ignore), and [octokit/webhooks](https://github.com/octokit/webhooks).
+
+The scaffolded `writing-great-skills` skill is vendored from [mattpocock/skills](https://github.com/mattpocock/skills), with its license included.
+
+## License
+
+[MIT](LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.

package/dist/agent.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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/).
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+/** Base64-encoded image reference. */
+export interface ImageRef {
+    mimeType: string;
+    data: string;
+}
+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;
+}
+export type AgentEvent = {
+    type: "text";
+    delta: string;
+}
+/** Model reasoning, streamed live. Process, NOT the answer: consumers MUST NOT fold it into the final text. */
+ | {
+    type: "thinking";
+    delta: string;
+} | {
+    type: "tool_started";
+    id: string;
+    name: string;
+    args: Json;
+} | {
+    type: "tool_ended";
+    id: string;
+    isError: boolean;
+    content: Json;
+}
+/** Terminal: success. `data` is attached only when the engine produces a structured result. */
+ | {
+    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). */
+ | {
+    type: "failed";
+    details: string;
+    retryable: boolean;
+    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.
+ */
+export declare const SESSION_BUSY_CODE = "session_busy";
+/**
+ * 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).
+ */
+export interface Agent {
+    invoke(scope: Scope, prompt: Prompt): AsyncIterable<AgentEvent>;
+}

package/dist/agent.js

@@ -0,0 +1,14 @@
+/**
+ * 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/).
+ */
+/**
+ * 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.
+ */
+export const SESSION_BUSY_CODE = "session_busy";

package/dist/channels/body.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read a request body with a hard byte cap (real bytes). A streaming cap is the only robust guard
+ * against an unbounded body (Content-Length is bypassable with chunked encoding). Web-streams only.
+ */
+export declare function readBodyCapped(req: Request, max: number): Promise<{
+    text: string;
+} | {
+    tooLarge: true;
+}>;

package/dist/channels/body.js

@@ -0,0 +1,29 @@
+/**
+ * Read a request body with a hard byte cap (real bytes). A streaming cap is the only robust guard
+ * against an unbounded body (Content-Length is bypassable with chunked encoding). Web-streams only.
+ */
+export async function readBodyCapped(req, max) {
+    if (!req.body)
+        return { text: "" };
+    const reader = req.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > max) {
+            await reader.cancel();
+            return { tooLarge: true };
+        }
+        chunks.push(value);
+    }
+    const buf = new Uint8Array(received);
+    let offset = 0;
+    for (const c of chunks) {
+        buf.set(c, offset);
+        offset += c.byteLength;
+    }
+    return { text: new TextDecoder().decode(buf) };
+}

package/dist/channels/github/github.d.ts

@@ -0,0 +1,31 @@
+import type { Schema } from "@octokit/webhooks-types";
+import type { ChannelModule } from "../../host/node.ts";
+/** A verified GitHub webhook event. Header fields plus the official typed payload. */
+export interface GithubEvent {
+    /** `X-GitHub-Event` (e.g. "pull_request", "issue_comment"). */
+    event: string;
+    /** `payload.action` (e.g. "opened"), when present — the usual routing discriminant. */
+    action?: string;
+    /** `X-GitHub-Delivery` — unique per delivery. */
+    deliveryId: string;
+    /** The native payload (union of all events); narrow it, e.g. `if ("pull_request" in event.payload)`. */
+    payload: Schema;
+}
+/** What `on` returns per acted-on delivery: a session + the prompt text for the agent turn. */
+export interface Intent {
+    session: string;
+    text: string;
+}
+export interface GithubChannelOptions {
+    /** Webhook secret — verifies inbound deliveries (HMAC-SHA256 over the raw body). */
+    secret: string;
+    /** Map a verified event to the intents this agent acts on (empty array = ignore). */
+    on: (event: GithubEvent) => Intent[];
+}
+/**
+ * Build a GitHub webhook channel: policy options in, a {@link ChannelModule} out (mounts
+ * `POST /webhook`). `agent` arrives via the mount context. The adapter owns that route key; to serve
+ * it elsewhere, re-key the returned module:
+ * `(ctx) => ({ "POST /gh": githubChannel(opts)(ctx)["POST /webhook"]! })`.
+ */
+export declare function githubChannel({ secret, on }: GithubChannelOptions): ChannelModule;

package/dist/channels/github/github.js

@@ -0,0 +1,80 @@
+/**
+ * GitHub webhook channel: verify → route via `on(event)` → fire-and-forget agent turns, ACK 202.
+ * The developer writes only `on`. Concurrency safety is the engine's per-session lease. A turn that
+ * fails after the 202, or an in-flight turn on shutdown, is lost (server log only).
+ */
+import { verify } from "@octokit/webhooks-methods";
+import { collect } from "../../collect.js";
+import { log } from "../../log.js";
+import { readBodyCapped } from "../body.js";
+import { text } from "../respond.js";
+/** Raw body cap before verification — GitHub caps webhook payloads at 25 MB; reject larger early. */
+const MAX_WEBHOOK_BYTES = 25 << 20;
+/**
+ * Build a GitHub webhook channel: policy options in, a {@link ChannelModule} out (mounts
+ * `POST /webhook`). `agent` arrives via the mount context. The adapter owns that route key; to serve
+ * it elsewhere, re-key the returned module:
+ * `(ctx) => ({ "POST /gh": githubChannel(opts)(ctx)["POST /webhook"]! })`.
+ */
+export function githubChannel({ secret, on }) {
+    // A non-empty secret is mandatory: verify() against an empty key accepts a signature anyone can
+    // compute, so an unset secret must fail at construction, never silently run forgeable.
+    if (!secret) {
+        throw new Error("githubChannel requires a non-empty secret (the GitHub webhook secret, e.g. GITHUB_WEBHOOK_SECRET)");
+    }
+    return ({ agent }) => ({
+        "POST /webhook": async (req) => {
+            if (req.method !== "POST")
+                return text("POST only\n", 405);
+            // Cap before verify: a public endpoint must not buffer an unbounded body (chunked bypasses Content-Length).
+            const body = await readBodyCapped(req, MAX_WEBHOOK_BYTES);
+            if ("tooLarge" in body)
+                return text("payload too large\n", 413);
+            const raw = body.text;
+            // Fail closed: verify() throws on an empty/missing arg, so treat any verify error as a clean 401.
+            const signature = req.headers.get("x-hub-signature-256");
+            if (!signature || !(await verify(secret, raw, signature).catch(() => false))) {
+                return text("invalid signature\n", 401);
+            }
+            const eventName = req.headers.get("x-github-event") ?? "";
+            if (eventName === "ping")
+                return new Response(null, { status: 204 });
+            // x-www-form-urlencoded (GitHub's UI default) wraps the JSON in a `payload` field; json is the body.
+            let json = raw;
+            if ((req.headers.get("content-type") ?? "").includes("application/x-www-form-urlencoded")) {
+                const field = new URLSearchParams(raw).get("payload");
+                if (field === null)
+                    return text("missing form payload\n", 400);
+                json = field;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(json);
+            }
+            catch {
+                return text("invalid json\n", 400);
+            }
+            const event = {
+                event: eventName,
+                action: typeof payload.action === "string" ? payload.action : undefined,
+                deliveryId: req.headers.get("x-github-delivery") ?? "",
+                payload: payload, // trust boundary: the verified body is a GitHub event
+            };
+            // Fire each turn, return 202; the process runs them to completion. The lifecycle is logged to
+            // stderr — after the 202 there is no response body, so these lines are the operator's only signal
+            // (and the sink that keeps a post-ACK error from going unhandled).
+            const intents = on(event);
+            const label = event.action ? `${event.event}.${event.action}` : event.event;
+            for (let i = 0; i < intents.length; i++) {
+                const { session, text } = intents[i];
+                // Per-turn correlation id (deliveryId is unique per webhook; the index disambiguates fan-out),
+                // threaded through start/done/failed so a terminal line joins back to its start.
+                const turn = `${event.deliveryId}#${i}`;
+                log.info(`[github] turn start: turn=${turn} session=${session} event=${label}`);
+                const startedAt = Date.now();
+                void collect(agent.invoke({ session }, { text })).then(() => log.info(`[github] turn done: turn=${turn} session=${session} (${Date.now() - startedAt}ms)`), (error) => log.error(`[github] turn failed: turn=${turn} session=${session} (${Date.now() - startedAt}ms): ${String(error)}`));
+            }
+            return new Response(null, { status: 202 });
+        },
+    });
+}

package/dist/channels/github/scaffold/channel.ts

@@ -0,0 +1,25 @@
+import { githubChannel } from "@fastagent-sh/fastagent/github";
+
+// A channel = a third-party ADAPTER (githubChannel: verify + parse + ACK) configured with YOUR on() policy.
+// fastagent discovers this file under channels/, mounts POST /webhook, and pipes the agent to the
+// adapter — this file holds only policy. Set GITHUB_WEBHOOK_SECRET in .env (a missing secret fails at
+// startup — an empty key would accept forged deliveries) and point a GitHub webhook (JSON) at POST /webhook.
+export default githubChannel({
+  secret: process.env.GITHUB_WEBHOOK_SECRET ?? "",
+  // Map a verified event to the intents the agent acts on (empty array = ignore). Each review is
+  // INDEPENDENT and idempotent (it reconciles against the PR's existing comments), so use a
+  // distinct per-delivery session (event.deliveryId): overlapping deliveries then run on their
+  // own session without a shared-lease drop.
+  on: (event) => {
+    if (event.event === "pull_request" && event.action === "opened" && "pull_request" in event.payload) {
+      const { repository, pull_request } = event.payload;
+      return [
+        {
+          session: event.deliveryId,
+          text: `Review pull request #${pull_request.number} in ${repository.full_name}.`,
+        },
+      ];
+    }
+    return [];
+  },
+});

package/dist/channels/http.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Agent } from "../agent.ts";
+/**
+ * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
+ * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
+ */
+export declare function createInvokeHandler(agent: Agent): (req: Request) => Promise<Response>;
+/**
+ * node:http adapter for a Fetch handler. Bridges IncomingMessage → Request and pumps the
+ * Response body back to ServerResponse with backpressure; a client disconnect (`res` close)
+ * cancels both the request signal and the response stream (→ invoke cancellation).
+ */
+export declare function nodeListener(handler: (req: Request) => Promise<Response>): (req: IncomingMessage, res: ServerResponse) => void;