feat(channels): add Max Messenger channel

[HumanGoClaude]

Summary

Adds Max (https://max.ru) as a first-class channel
under internal/channels/max/, following the same factory-registration
pattern as Telegram, Discord, Slack, Feishu, WhatsApp, Zalo OA, Zalo
Personal, Facebook, and Pancake. The new package supplies long-poll
and webhook transports, in-place streaming edits, allowlist / pairing
access control, and inbound / outbound media. Admin UI integration is
included so operators can create Max channels through the dashboard.

The backend wires through three small touch-points (one line each in
cmd/gateway.go, internal/channels/channel.go, and
internal/http/channel_instances.go). The admin dashboard receives Max
through five entries in the existing schema-driven channel forms — no
new components, just data added to the schemas already used by Discord,
Facebook, and Pancake.

The diff totals 48 files / +8,076 / −21 — large because the new
backend package is test-heavy: 3,188 LOC of production Go with
3,559 LOC of unit/integration tests + 173 LOC of JSON fixtures
captured from real API responses (a 1.12× test-to-production ratio).
The remaining ~1,140 LOC are documentation. The UI portion is 20 LOC of
TypeScript schema entries — no React components — so no UI test layer
was added (same pattern as Discord / Facebook / Pancake schemas).

Type

• Feature
• Bug fix
• Hotfix (targeting main)
• Refactor
• Docs
• CI/CD

Target Branch

dev (per CONTRIBUTING.md).

Checklist

• go build ./... passes
• go build -tags sqliteonly ./... passes
• go vet ./... passes
• Tests pass: go test -race ./...
• Web UI builds: pnpm lint + pnpm build pass
• No hardcoded secrets or credentials
• SQL queries use parameterized $1, $2 (no new SQL — uses the
  existing channel_instances table only)
• New user-facing strings added to all 3 locales (en/vi/zh)
  (only the pairing-reply text and "💭 Thinking..."
  streaming placeholder are new; both are English defaults
  identical in approach to Telegram, Discord, Slack — none of
  the existing channels localize these strings via
  i18n.Catalog)
• Migration version bumped in internal/upgrade/version.go (if new migration)
  (no migration — uses existing channel_instances table with
  channel_type='max')

Test Plan

Automated

• 241 unit tests in the new internal/channels/max/ package,
  covering: HTTP client, inbound translator, outbound dispatcher,
  chunker, streaming state machine, webhook signature verification,
  HMAC for request_contact, media download/upload, reactions,
  policy translator (DM + group), and a lifecycle integration_test.go
  exercising start → poll → policy → dispatch → stream → finalize.
• All tests pass under go test -race -count=1 -timeout=120s ./internal/channels/max/... (~20 s).
• Full repo go test -count=1 -short ./... is green — no regression
  in any other package.
• Build matrices: go build ./... and go build -tags sqliteonly ./...
  both pass. go vet ./... clean. gofmt clean on every file
  touched by this PR.
• Frontend toolchain: Node 22 + pnpm 10 (matching CI's web job).
  pnpm install --frozen-lockfile resolves cleanly, pnpm lint reports
  zero errors, tsc -b && vite build transforms 6,077 modules without
  errors.

Manual

End-to-end validation against a real Max bot in a local goclaw stack:

• Channel created through the admin UI (Channels → Add Channel →
  Max), POST /api/channel-instances with channel_type=max.
  Channel reaches healthy state after probing GET /me.
• DM from a test user → policy check (dm_policy=open) → agent loop
  → streaming placeholder edits with throttled markdown finalisation
  → final reply delivered with citations from web_fetch tool.
• DM under dm_policy=pairing from an unpaired user → pairing-code
  reply sent via Max API; agent loop is not triggered (verified
  the security gate works).
• Group code is implemented but not exercised live — Max platform
  does not yet permit adding bots to chats. Group policy logic is
  unit-tested.
• Webhook mode is implemented and unit-tested but has not been
  exercised against the production Max API yet. Polling is the
  recommended primary mode and the only one validated end-to-end.

---

Why this design

Max (https://max.ru) is a messaging platform popular
in Russia (>140M MAU), with a documented Bot API at
platform-api.max.ru. There is no widely-adopted Go SDK for it, so the
channel uses a small net/http client directly. The API surface in use
is deliberately narrow (~10 endpoints), which keeps the client simple
enough to maintain in-tree without a third-party dependency — same
reasoning by which goclaw uses stdlib + a thin client for several
existing channels.

The package mirrors existing channels' conventions:

• Embeds BaseChannel for shared allowlist/pairing/health logic
• Self-registers through instanceLoader.RegisterFactory
• Publishes inbound to MessageBus; consumes outbound from
  MessageBus
• Uses the same PairingStore and PendingMessageStore shared
  services
• Implements StreamingChannel, WebhookChannel, ReactionChannel,
  BlockReplyChannel — the same optional interfaces other channels
  expose

Notable choices specific to Max:

• Two transports in one package (polling + webhook) selected by
  config.mode. Splitting them would duplicate the inbound translator
  and the policy wiring; existing channels with multiple transport
  modes (WhatsApp bridge vs. native, Slack bot vs. user) keep them
  in one package.
• Streaming uses plain text during edits, then re-emits as
  markdown on final Send(). Max's markdown parser breaks on partial
  syntax mid-stream.
• request_contact HMAC verified with hmac.Equal for
  constant-time comparison; distinct error types for malformed hex
  vs. tampered payload.
• Admin UI integration is data, not code. The dashboard generates
  channel forms from configSchema and credentialsSchema. Adding
  Max meant a few schema entries and channel-type list additions
  across 5 existing files (~20 LOC total) — no new TSX components,
  mirroring how Discord, Facebook, and Pancake are integrated.

What's in this PR

Category	Files	Notes
Backend channel	28 .go files in internal/channels/max/ (+ README.md, 7 testdata/*.json)	Self-contained package
Backend wiring	cmd/gateway.go, internal/channels/channel.go, internal/http/channel_instances.go	One added line each (factory registration, TypeMax constant, validator entry)
Admin UI	5 files in ui/web/src/ (constants/channels.ts, pages/channels/channel-schemas.ts, pages/channels/channels-status-utils.ts, pages/config/sections/bindings-section.tsx, pages/contacts/contacts-page.tsx)	Schema-driven; +20 LOC, no new components
Docs	docs/05-channels-messaging.md, README.md, CLAUDE.md, CHANGELOG.md	Channel-count bump, new section, file-tree entry, Unreleased entry
Other	.gitignore (+3 lines for local smoke binary)	Keeps the repo root clean

The diff in cmd/gateway.go shows the 1 new factory-registration
line plus a few lines of goimports re-grouping that the formatter
applied automatically when the file was opened. Happy to revert the
re-grouping if you prefer the patch strictly minimal.

Backwards compatibility

• New channel type. No existing behaviour changes.
• Schema unchanged (see migration note in the Checklist above).
• New feat(channels/max) Conventional-Commits scope follows the
  per-channel scoping convention.

Follow-ups (separate PRs, after this one merges)

1. User-facing setup guide — docs(channels): add Max setup guide in nextlevelbuilder/goclaw-docs (modeled on
   channels/telegram.md)
2. Webhook end-to-end validation — once a public HTTPS endpoint
   is available, exercise webhook mode against the live API and
   tighten the "known limitations" wording
3. Channel Comparison matrix — add a Max column to the table at
   docs/05-channels-messaging.md § 4

Reviewer suggested order

If you'd like to slice the review:

1. internal/channels/channel.go (1 line) — confirm constant placement
2. cmd/gateway.go (1 substantive line — the RegisterFactory
   call) — confirm wiring matches the pattern
3. internal/channels/max/factory.go — config + creds shape
4. internal/channels/max/max.go — lifecycle and embedded
   BaseChannel
5. internal/channels/max/inbound.go + policy.go — request flow,
   policy enforcement
6. internal/channels/max/outbound.go + stream.go + format.go
   — response flow + chunking
7. internal/channels/max/webhook.go + auth.go — alt transport
   and HMAC
8. Tests — *_test.go, especially integration_test.go
9. ui/web/src/pages/channels/channel-schemas.ts — credentialsSchema.max
   and configSchema.max mirror factory.go's InstanceConfig
10. Other UI files — small enum/array additions
11. Docs — docs/05-channels-messaging.md Max section + extended
    interfaces table

Happy to squash the commit history or drop the webhook mode if you'd
prefer a narrower scope.

Origin

The 20 commits split into 15 code (feat/fix/test/chore)
and 5 docs. Branch is linear, no merge commits. Branch is based
on the public v3.11.2 tag — every commit is reachable from it. The
work was developed on a separate fork
(HumanGoClaude/goclaw_max_channel)
to allow iterative testing before upstreaming; this branch
(feat/max-channel) is the version targeting dev.