Add HELM-governed Telegram channel bridge (HITL-by-phone) - #20
Merged
Conversation
Adopt the Rowboat ChannelBridge mechanism (Apache-2.0) as governed HITL-by-phone: a transport-agnostic command bridge plus a dependency-free Telegram Bot API transport. - Every inbound command (help/list/status/resume/new/stop, chat turns, ask_human answers) is preflighted through the HELM Kernel /api/v1/evaluate contract with a distinct action URN; only explicit ALLOW dispatches. Unknown verdicts, ESCALATE, evaluator outages, and unknown slash-commands all fail closed to denial. - ask_human relay: suspended-turn questions are delivered to the chat and answers are Kernel-evaluated before being routed back into the turn. - autoPermission only for explicitly allowlisted routine read-only commands (default help/list/status); chat turns run with autoPermission=false unless the operator deliberately allowlists them. - Telegram transport: DMs only, explicit chat-ID allowlist (empty denies everyone), persisted poll offset (no re-execution after restart), terminal 401/404 handling. Bot token via HELM_TELEGRAM_BOT_TOKEN env var only; never logged or embedded in messages. - Tests use a fake transport, fake session engine, fake evaluator, and an in-memory event bus: command-to-turn evaluation, ask_human round trip, deny-by-default paths, autoPermission allowlist, offset persistence, and transport authorization. No network, no credentials. WhatsApp/baileys intentionally excluded (unofficial protocol).
|
Strix is installed on this repository, but we couldn't run this PR security review because this workspace's trial has ended. Add a card to resume code reviews here. |
…utes, enable dependency caching CI efficiency sweep. - PR gates no longer rebuild every change twice (squash-merge + up-to-date-branch policy already test against main) - concurrency cancels superseded in-progress runs - timeout-minutes bounds runaway jobs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adopts Rowboat's ChannelBridge mechanism (Apache-2.0, rowboatlabs/rowboat) as governed human-in-the-loop by phone, per the Wave-2 deep study (
.tmp-research/findings/x-core-services.md, mechanism 4 + recommendation 3; Rowboat sourceschannels/{bridge,service}.ts,channels/transports/telegram.ts). Rowboat runs channel turns withautoPermission: trueand no per-command policy; this package is an original implementation that makes every hop Kernel-evaluated — the outperform wedge.New package:
packages/js/helm-channel-bridge(+integrations/telegram/README.md), following the existinghelm-tool-wrapperconventions (thin adapter,/api/v1/evaluateboundary style, node:test, no runtime deps).Governance semantics (fail closed)
help/list/status/resume/new/stop, chat turns, andask_humananswers each preflight with a distinct action URN (channel.<transport>.command.<name>,channel.<transport>.turn.run,channel.<transport>.ask_human.answer). Only explicitALLOWdispatches; unknown verdicts,ESCALATE, evaluator outages, and malformed responses all deny. Unknown slash-commands are denied locally without evaluation or dispatch.help/list/status. Chat turns runautoPermission: false(tool effects still need approval) unless the operator deliberately allowlistschat— documented as a risky choice.HELM_TELEGRAM_BOT_TOKENenv var only — never logged, never in code/tests/messages.Test evidence
18/18 tests pass (fake transport + fake session engine + fake evaluator + in-memory event bus; no network, no credentials):
Coverage: command→turn evaluation URNs/effect classes, dispatch on ALLOW only, DENY/ESCALATE/unknown-verdict/evaluator-outage fail-closed paths with receipt surfaced, unknown slash-command denial (evaluator untouched), ask_human round trip incl. denied-answer isolation, autoPermission default vs operator allowlist, stop-after-ALLOW, Telegram DM/allowlist/group/bot authorization, offset persistence + restart resume, terminal 401/404, token non-leakage.
Full repo validation (
make validate): helm-tool-wrapper JS tests, helm-channel-bridge JS tests, 20 Python wrapper tests, and sample receipt/EvidencePack verification all pass.CI:
helm-boundary-check.ymlgains install+test steps for the new package;Makefile test-jscovers both packages.Out of scope / handoff
ChannelSessions/ChannelTurnEventSourceare minimal interfaces; wiring them to a live governed runtime (e.g. helm-ai-kernel agentruntime from Wave 1) is a Wave-3 integration task.scripts/generate_samples.py).