openhuman/docs/plans/tinychannels-integration.md

TinyChannels Integration Plan

Plan for adopting the tinychannels crate (~/work/tinyhumansai/tinychannels) as the typed channel layer, deleting the duplicated copies in this repo, and fixing the channel bugs surfaced by the 2026-07-04 cross-repo audit.

Companion docs in the tinychannels repo:

• docs/spec/openclaw-hermes-channel-porting.md — the upstream research spec.
• docs/spec/tinychannels-execution-plan.md — the crate-side phased plan. Steps below reference its phases.

Current State

• This repo now depends on tinychannels through the TinyChannels feat/phase-0-hygiene branch while the companion PR lands. The first duplicate-removal pass has landed:

  openhuman-4 file	tinychannels file
  src/openhuman/channels/traits.rs	re-exports src/traits.rs
  src/openhuman/channels/controllers/definitions.rs	re-exports src/controllers/definitions.rs
  src/openhuman/channels/controllers/schemas.rs schema declarations	converts from src/controllers/schemas.rs
  src/openhuman/channels/controllers/ops/connect.rs allowlist/key helpers	calls src/controllers/credentials.rs
  src/openhuman/channels/controllers/ops/types.rs	re-exports src/controllers/types.rs
  src/openhuman/config/schema/channels.rs	re-exports provider config from src/config.rs, while keeping OpenHuman-owned security/sandbox config local
  src/openhuman/channels/context.rs key/constants helpers	calls/re-exports src/context.rs where type-compatible
  src/openhuman/channels/runtime/supervision.rs in-flight sizing	re-exports src/runtime.rs::compute_max_in_flight_messages
  Telegram/Discord text splitting	calls src/text.rs chunker with UTF-16 measurement

• OpenHumanChannelBackend now lives in src/openhuman/channels/controllers/backend.rs and implements tinychannels::ChannelBackend by delegating to the existing channels/controllers/ops/{connect,messaging,discord,telegram}.rs flows.

• The crate-side Phase 5 relay contract now includes typed gateway/connector relay frames, the request/response frame transport loop, a feature-gated WebSocket dialer with reconnect supervision, and a portable relay runtime config shape under channels_config.relay. OpenHuman now enables the crate's relay WebSocket feature and starts the relay runtime for complete relay config.

• The metadata controllers (channels.list / channels.describe) now use ChannelManager for definition lookup. The channels.status and channels.test controllers now route through ChannelManager<OpenHumanChannelBackend>, preserving the existing no-log JSON response shapes while using the crate manager for definition lookup and credential validation where applicable. channels.get_default also routes through the manager while preserving the public { active_channel } response, channels.connect and channels.set_default preserve their public log/value envelopes after manager dispatch, and the managed Telegram/Discord link controllers route through the manager while preserving their no-log typed responses. The no-log send/reaction/thread controllers now dispatch through the manager and unwrap the backend raw payload to preserve legacy top-level JSON shapes; channels.send_message, direct channel-bus backend sends, and legacy runtime/proactive/provider-helper Channel::send callers now cross the crate intent bridge as ChannelOutboundIntents and get deterministic idempotency keys before legacy backend/provider calls. channels.disconnect also routes through the manager while preserving the old log string and extra fields such as memory_chunks_deleted. Discord guild/channel/permission discovery dispatches through the manager while restoring the old log strings and top-level provider JSON. Outbound sends now use the live relay transport for configured relay identities. The remaining OpenHuman work is still full session identity switchover, provider extraction, and the planned test split below; the first envelope slice is landed because the runtime now publishes a TinyChannels ChannelInboundEnvelope on ChannelMessageReceived events, memory conversation persistence records the TinyChannels session key as migration metadata, and startup now has a relay inbound handler that preserves the original authenticated relay envelope, including scope_id, from the live relay socket through dispatch.

Step 1 — Add the dependency, delete duplicates

• Landed: Add the tinychannels git dependency to Cargo.toml (single crate, not a workspace; edition 2021 depending on an edition-2024 crate is fine).
• Landed for the first slice: Delete the duplicated definitions/types/traits/config-schema/helper code and re-export from the old paths so the 100+ call sites keep compiling:
  • src/openhuman/channels/mod.rs: pub use tinychannels::{Channel, ChannelMessage, SendMessage, ...};
  • src/openhuman/channels/controllers/...: re-export ChannelDefinition, ChannelAuthMode, response types.
  • src/openhuman/config/schema/channels.rs: re-export ChannelsConfig and provider config structs. Note tinychannels inlined EmailConfig and YuanbaoConfig, which this repo currently sources from channels::email_channel / providers::yuanbao — repoint those two to the crate and delete the local definitions.
• Still pending: delete migrated in-module tests once each suite is fully represented in tinychannels. The duplicate definitions, config-schema, and in-flight sizing helper suites have been deleted; keep everything provider- or app-specific (see Step 4).
• Do not remove sandbox/security config from this repo based on the crate's copy: the crate is dropping its unwired SecurityConfig/SandboxConfig cluster as scope creep; this repo's originals (if used) stay where they are.

Step 2 — Implement ChannelBackend

• Landed: New OpenHumanChannelBackend in src/openhuman/channels/controllers/backend.rs, delegating each trait method to the existing ops functions:
  • send_message → messaging.rs::channel_send_message (already composes effective_backend_api_url + jwt::get_session_token + BackendOAuthClient), with send_message_value preserving OpenHuman's arbitrary rich-message JSON for the public RPC controller.
  • connect_channel / disconnect_channel → connect.rs flows plus credentials::ops::{store,remove}_provider_credentials (keyed "channel:<slug>"), with disconnect returning the raw legacy payload for fields such as memory_chunks_deleted.
  • channel_status / test_channel → existing status/test ops plus health::snapshot.
  • Telegram login and Discord link/guild/permission methods → the existing telegram.rs / discord.rs ops.
• Landed: The current channels.* controller entry points dispatch through ChannelManager<OpenHumanChannelBackend> where they cross this crate seam, while preserving the legacy public JSON/log envelopes.
• The event bus, health bus, and dispatch engine stay app-side and drive tinychannels. Never add a tinychannels → openhuman dependency; the runtime/ dispatch engine and the web provider are consumers of the crate, not porting candidates (they import ~45 openhuman modules).

Step 3 — Bug fixes coordinated with the crate

Fix these here in lockstep with tinychannels Phase 1/2 (same semantics, one implementation — prefer calling the crate's new helpers over patching local copies):

1. Landed: UTF-16 chunking. Telegram and Discord splitting now call the crate's Phase 2 chunker with UTF-16 code-unit measurement and markdown fence preservation.
2. Landed for existing helper semantics: Telegram history keys. channels/context.rs now delegates to the crate helper, preserving OpenHuman's current Telegram topic behavior. Runtime received-message events now also carry the crate's normalized inbound envelope, with Telegram thread_ts projected as topic_id; conversation persistence records the TinyChannels session key when an event carries an envelope. Relay inbound now preserves the relay-supplied envelope and scope_id through dispatch. Full non-relay session identity switchover still needs provider-sourced scope_id.
3. Partially landed for relay inbound; non-relay providers still deferred: workspace/tenant discriminator. Session keys (channels/bus.rs:1005-1042) omit guild/team/tenant; Slack channel ids are only workspace-unique. Relay inbound carries the relay envelope's scope_id through received-message events; provider-originated legacy messages still need native envelope construction with provider-sourced scope. Deferral reason: adding scope to the current legacy string keys would change conversation identity without the envelope migration that can preserve compatibility aliases.
4. Landed for portable send boundaries; provider wire enforcement remains platform-specific. No idempotency key exists on legacy sends; a retry after a transport error double-posts. channels.send_message now routes through a crate ChannelOutboundIntent at the ChannelBackend seam while preserving the legacy public RPC response and backend JSON shape. The direct channel bus backend sends and runtime/proactive/provider-helper Channel::send paths use the same crate bridge, carrying deterministic idempotency keys through SendMessage. Provider-specific use of those keys on external wire APIs remains Phase 6/platform work.
5. Deferred pending product decision: conversation_memory_key intent check. It keys on msg.id (per-message, not per-conversation) and this repo's tests assert that behavior (tests/memory.rs). Confirm whether per-turn keying is intended; the crate will rename or fix accordingly — this repo should follow.

Step 4 — Test split

• Partly landed: the portable controllers/schemas_tests.rs schema-catalog assertions, pure allowlist/key helper tests, catalog/request-shape halves of controllers/ops_tests.rs, backend-agnostic default-channel validation, and config-backed channel status detection now live in tinychannels. The duplicate definitions suite, config-schema assertions, in-flight sizing helper assertions, and portable schema-catalog assertions were deleted here. This repo keeps handler parity, adapter conversion, params, legacy envelope helper tests, local security/sandbox config defaults, supervisor classification tests, and app-side persistence/REST wiring tests.
• Still migrate to tinychannels: any remaining backend-agnostic assertions from controllers/ops_tests.rs, rewritten against a mock ChannelBackend, plus the already-mirrored suites listed in Step 1.
• Stay here: all providers/*_tests.rs (telegram 148, web 93, imessage 58, discord 55+23, email 50, lark 42, whatsapp 41+29, irc 37, mattermost 33, signal 32, presentation 29, linq 23, qq 11), bus_tests.rs, routes_tests.rs, runtime/dispatch_tests.rs, runtime/startup_tests.rs, and the harness-driven tests/ integration files (prompt, telegram/discord integration, runtime tool calls, health, identity).
• The REST-wiring halves of ops_tests.rs become the test bed for OpenHumanChannelBackend (Step 2).

Step 5 — Provider extraction ladder (later, tracks crate Phase 6)

Move provider wire code into tinychannels only when its dependencies reduce to crate traits:

1. Now portable (no cross-module imports): email, irc, yuanbao, cli, imessage, mattermost, qq, dingtalk, presentation.
2. After a configured-HTTP-client trait (replaces config::build_runtime_proxy_client / apply_runtime_proxy_to_builder): discord, slack, whatsapp, lark, signal.
3. After approval, voice/STT, pairing, and conversation-memory traits: telegram (imports approval, voice::create_stt_provider, memory_conversations, security::pairing).
4. Never: web provider and runtime/ dispatch — they are the harness front-end and orchestrator that consume the crate.

Sequencing and risk notes

• Land Step 1 and Step 2 together in one PR if possible: adding the dep while keeping duplicates invites split-brain imports (some call sites on the crate types, some on the local copies — Rust will treat them as different types).
• Session-key changes (Step 3, items 2–3) change conversation identity. Ship them behind the crate's legacy-key canonicalization with a migration test that maps a sample of existing keys to new keys losslessly.
• Positive invariants to preserve (verified in the audit): no secrets are logged in the channels tree, and no blocking calls exist in async provider paths. Any moved code must keep both properties.