Greptile Summary

This PR fixes a validation bug in agentHandlers.agent where channel/replyChannel values of heartbeat, cron, or webhook caused a 400 rejection when spawning subagents from non-delivery-triggered parent runs. The fix introduces a typed INTERNAL_NON_DELIVERY_CHANNELS constant and isInternalNonDeliveryChannel predicate in message-channel-constants.ts, re-exports them from the barrel, and widens isKnownGatewayChannel in agent.ts to accept these values alongside gateway message channels. The changes are minimal, well-scoped, and covered by both unit and integration tests.

Confidence Score: 5/5

This PR is safe to merge — the change is a narrow, additive fix with clear tests and no impact on existing delivery-channel logic.

The fix is minimal and additive: a new constant, a typed predicate, and a single || in the validation guard. isGatewayMessageChannel is unchanged, so existing delivery-channel paths are unaffected. The normalization pipeline (normalizeMessageChannel lowercases before the predicate is called) is consistent with the new constants being lowercase, and the unit tests explicitly cover the direct-predicate no-case-folding behavior. No security or data-integrity concerns identified.

No files require special attention.

_{Reviews (1): Last reviewed commit: "fix(gateway): accept heartbeat/cron/webh..." | Re-trigger Greptile}

The two failing checks (checks-node-core-fast-support and checks-node-core) are pre-existing on main and unrelated to this PR. The failing tests are:

• test/scripts/plugin-boundary-report.test.ts — expected 'private-package-core-integrated' to be 'private-core-bridge'
• src/memory-host-sdk/host/embeddings.test.ts — Cannot find package 'node-llama-cpp' (5 tests)

Same job names, same failures, on main run 25034307683 at commit 996818e6 ("fix: follow up main ci failures") — i.e. main has been red on these two jobs since before this branch existed. This PR only touches src/utils/message-channel*, src/gateway/server-methods/agent.ts, and their colocated tests; none of those areas involve plugin-boundary-report or node-llama-cpp embeddings.

Per CONTRIBUTING.md:

"Do not submit test or CI-config fixes for failures already red on main CI."

Happy to rebase once main is green if that helps the merge queue.

Rebased onto current main (27e31305) — main went green at 05:36 with 252cc7ec test: fix unit-fast config assertion + 27e31305 test(gateway): keep session event suite minimal, which fix the plugin-boundary-report and node-llama-cpp shards I described above. CI should now run clean.

No code changes — same 5-file diff (+86/-1).

Codex automated review: keeping this open.

Keep this PR open. Current main still rejects heartbeat, cron, and webhook channel hints in the gateway agent handler, while the linked bug remains open. The PR is a focused implementation candidate: it widens validation only for named internal non-delivery hints, keeps unknown channels fail-closed, and adds regression coverage for both channel and replyChannel.

Best possible solution:

Keep this PR open and review or land it, or land an equivalent main-branch fix. The implementation should accept heartbeat, cron, and webhook only as internal non-delivery agent channel hints, preserve isGatewayMessageChannel semantics for actual delivery decisions, and keep regression tests for channel and replyChannel acceptance plus genuine unknown-channel rejection.

What I checked:

• Current main still validates only gateway message channels: At current main, agent param validation defines isKnownGatewayChannel as exactly isGatewayMessageChannel(value), then rejects any normalized channel or replyChannel hint that is not last and fails that predicate with invalid agent params: unknown channel. (src/gateway/server-methods/agent.ts:543, c3c8d66acf95)
• Current gateway channel set excludes the requested non-delivery sources: The current channel constants define only webchat as the internal message channel, and listGatewayMessageChannels is deliverable channels plus that single internal channel. There is no INTERNAL_NON_DELIVERY_CHANNELS equivalent on main. (src/utils/message-channel-normalize.ts:35, c3c8d66acf95)
• Subagent spawn can still forward the requester channel hint: The sessions_spawn path calls the gateway agent method and passes channel: childSessionOrigin?.channel into the child agent call, so a non-delivery parent origin can still hit the gateway channel validation before the child run starts. (src/agents/subagent-spawn.ts:1057, c3c8d66acf95)
• Current tests cover rejection, not acceptance: Main has tests that reject unknown channel/replyChannel hints, but no acceptance coverage for heartbeat, cron, or webhook. A grep for the linked bug and the proposed non-delivery predicate found no implementation or changelog entry on current main. (src/gateway/server.agent.gateway-server-agent-a.test.ts:271, c3c8d66acf95)
• Linked bug is still open and matches this PR: The live issue report for sessions_spawn rejects non-delivery channels (heartbeat, webhook, cron) #73237 says sessions_spawn from heartbeat, cron, or webhook parents fails with invalid agent params: unknown channel, and it remains open.
• PR diff is a narrow additive fix with tests: The final PR file list adds INTERNAL_NON_DELIVERY_CHANNELS and isInternalNonDeliveryChannel, composes that predicate into gateway agent validation, adds channel and replyChannel acceptance tests plus unknown-hint rejection tests, and adds a changelog entry. (src/gateway/server-methods/agent.ts:541, ec288e329272)

Remaining risk / open question:

• Closing this PR now would leave the open sessions_spawn rejects non-delivery channels (heartbeat, webhook, cron) #73237 regression unresolved on main.
• No tests were run because this was a read-only cleanup review; maintainers should still require touched-surface test or CI proof before merge.

Codex Review notes: model gpt-5.5, reasoning high; reviewed against c3c8d66acf95.