Addresses review feedback that channel-host.mts is doing too much.
Two changes, both scoped to the starters:
1. Channel construction moves to a new `channels.mts` beside `agent.ts` —
name resolution, `createChannel`, and the `onMessage` handler. That is
also the file to edit to customise a Channel (commands, reactions,
onMention), which previously meant editing the host.
The per-framework agent import moves with it, so `channel-host.mts` is now
byte-identical in all 15 starters rather than 13 + 2.
2. The host no longer stands up an HTTP server. Its comment claimed the
server was what "keeps the lifecycle-owning process alive"; that is false.
An open undici WebSocket holds the event loop on its own — verified with a
standalone repro where a process with no HTTP server and no timers of its
own stayed up indefinitely on a single WebSocket connection. The server was
therefore serving a second, uncalled copy of the runtime API on port 8300
for no reason.
With the server gone, `createCopilotNodeListener` was the wrong factory —
it builds a request listener purely for its activation side effect. The
host now uses `createCopilotRuntimeHandler` + `ready()`, which is the
documented long-running-host pattern (see fetch-handler.ts). This also
drops `node:http`, `basePath`, and the CHANNEL_PORT env var.
Behaviour is unchanged: same Channel, same agent, same status reporting, and
the same non-zero exit on activation failure.
Verified: 14/14 starters with a `typecheck:channel` script pass; mastra has no
such script by design (166dc94691) and its pre-existing Mastra `Memory` type
error is byte-identical before and after. `npm run channel` exercised on both
failure paths — missing channels.json, and missing INTELLIGENCE_API_KEY with a
name supplied — confirming the new `./channels.mjs` specifier resolves under
tsx as well as tsc. `parity:check` output identical to the pre-change baseline.
Refs #6315
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The starter READMEs, channel-host.mts headers, and the host's own log
lines described the feature as a "managed Channel". Managed is an
implementation detail of how Intelligence attaches the provider edge,
not part of the name — the product surface is just a Channel.
Renames every occurrence across the 15 starters. Section headings become
"Running a Channel", the host header becomes "Channel host", and the
setup_required log reads "no provider is attached yet".
"managed Intelligence" in the .env.example comments is left alone: that
one distinguishes hosted Intelligence from a self-hosted deployment and
is unrelated to Channel naming.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ready() resolves once every declared Channel reaches `online` or
`setup_required` — the latter means the Channel is declared but has no
managed provider attached yet, a normal waiting state rather than a
failure. The host used to log an unconditional "holding managed Channel"
success line in both cases, so a developer who has not finished
installing the provider app would see success, message the bot, and get
silence with no diagnostic.
The host now calls status() after ready() and reports the truth per
Channel: "is online" when actually online, or "declared but no managed
provider is attached yet" (pointing at `copilotkit channels status`)
when only setup_required. A ready() rejection still exits non-zero,
unchanged.
Propagated to all 15 starters (byte-identical apart from the
mcp-apps/a2a-middleware import line, as before), and updated the
langgraph-python README section describing the new log output.
Review findings on the managed Channel host in langgraph-python:
- Add "typecheck:channel" (tsc -p tsconfig.channel.json --noEmit) so
channel-host.mts has a repeatable typecheck now that it sits outside the
parity-tracked root tsconfig.json's include set. Passes clean (no new
errors, no skipLibCheck/any widening needed).
- resolveChannelName() no longer conflates a missing .copilotkit/channels.json
with a malformed one. Reading and parsing are now separate try blocks: a
missing file keeps the existing "run channels add" message, a parse
failure says the file exists but could not be parsed and includes the
underlying error, instead of misdirecting to re-add the channel.
Extracts agent construction into src/agent.ts so the runtime route and the new
channel-host.mts share one definition. The host holds no provider credentials and
declares no adapters: Intelligence owns the provider edge, so one host file works
for every provider.
Also adds tsconfig.channel.json, used only by the new "channel" script
(tsx --tsconfig tsconfig.channel.json channel-host.mts). Without it, tsx crashes
before the host's own code runs: the starter's tsconfig.json sets allowJs: true
(the create-next-app default, present in all 15 starters), which makes tsx's
CJS resolver prefer a sibling .ts file over the real .js entry point for *any*
node_modules package on a bare-specifier require -- including fast-json-patch
(pulled in transitively via @ag-ui/client), whose published package ships an
orphan index.ts (a source re-export of ./src/core) without the src/ directory
it points at. tsconfig.channel.json omits allowJs so this never triggers, and
does not touch the app's real tsconfig.json (which is parity-tracked verbatim
across other starters -- confirmed by testing the alternative fix first).
Full verification trail, including this deviation and the reasoning above, is
in .superpowers/sdd/2026-08-01-channel-host-in-starters/task-1-report.md.
Mike Ryan