4dfe63b4e2
Sibling to kei-notify-telegram (outbound only). This crate is the inbound
half of the Telegram Bot API integration — receives POST /webhook from
Telegram, verifies secret token, parses Update, emits typed WebhookEvent.
Architecture: handler-only. The crate exposes `handle_webhook` and the
parsed types; the consumer owns the axum::Router and the HTTP server.
This keeps kei-telegram-webhook composable into kei-buddy, kei-gateway,
or any other consumer without forcing a server topology.
Files (9 new, 484 LOC total, all under 200/file):
* src/update.rs — lean Telegram Update / Message / User / Chat /
CallbackQuery structs (only fields KeiBuddy needs: chat_id, from,
text, message_id, date, callback_data; #[serde(default)] on optionals)
* src/event.rs — WebhookEvent enum (Text / Callback / Other) +
classify(update) -> WebhookEvent
* src/handler.rs — axum handler with X-Telegram-Bot-Api-Secret-Token
header verification (mismatch → 401)
* src/context.rs — WebhookContext trait (consumer provides
secret_token() + on_event())
* src/error.rs — WebhookError via thiserror
* src/lib.rs — module declarations + re-exports
* Cargo.toml — workspace member, maturity = "alpha"
* README.md — usage example (axum Router mount, 10-line snippet)
Tests (5 in src/event.rs + src/handler.rs, all pass):
* classify_text_message — text Update → WebhookEvent::Text
* classify_callback_query — callback Update → WebhookEvent::Callback
* classify_other_returns_other — edited_message-only Update → Other
* bad_secret_token_returns_401 — wrong header → 401 UNAUTHORIZED
* good_secret_token_returns_200 — matching header → 200 OK
Verify-before-commit (RULE 0.13 §):
* cargo check --offline -p kei-telegram-webhook: PASS
* cargo test --offline -p kei-telegram-webhook --lib: 5 passed / 0 failed
* cargo check --workspace --offline: PASS (no new warnings)
STATUS-TRUTH from agent: shipped=functional, stubs=0, behaviour-verified=yes.
Follow-up (deferred, not blocking):
* axum is direct dep "0.7" in this crate + kei-cortex + kei-forge —
workspace should adopt axum in [workspace.dependencies] for version
unification (separate consolidation wave)
* Unmodelled Telegram fields (edited_message, inline_query, photo,
document, reply_markup) — extend when KeiBuddy needs them
|
||
|---|---|---|
| .. | ||
| _rust | ||
| templates | ||
| design-scrape.sh | ||
| figma-tokens.sh | ||
| frontend-inspect.sh | ||
| harden-base.sh | ||
| kei-ci-lint.sh | ||
| kei-docs-scaffold.sh | ||
| kei-doctor.sh | ||
| kei-sleep-queue.sh | ||
| kei-sleep-setup.sh | ||
| kei-sleep-sync.sh | ||
| live-preview.sh | ||
| log-ship.sh | ||
| MANIFEST.toml | ||
| metrics-scrape.sh | ||
| provision-hetzner.sh | ||
| provision-vultr.sh | ||
| README.md | ||
| screenshot-decode.sh | ||
| tomd.sh | ||
_primitives — first-class building blocks
_primitives/ holds standalone utilities that agents, hooks, and skills
(including /compose-solution) depend on. Unlike _blocks/ (behavioral
markdown) or _manifests/ (agent TOML), primitives are executable shell
programs installed at $HOME/.claude/agents/_primitives/ by install.sh.
Current primitives
| Primitive | Purpose | Invocation |
|---|---|---|
tomd.sh |
Universal non-native-format → markdown converter (PDF, DOCX, XLSX, PPTX, CSV, images, code). | ~/.claude/agents/_primitives/tomd.sh <file> |
tomd.sh is a first-class primitive. Universal non-native-format →
markdown converter with configurable cache directory
(KEISEI_TOMD_CACHE) and KeiSeiKit-style error tags ([tomd]).
Hook integration
hooks/tomd-preread.sh is a PreToolUse(Read) hook that auto-redirects
Claude to the converted markdown when a Read targets .docx / .doc / .xlsx / .pptx / .csv. Cached under $KEISEI_TOMD_CACHE (default
/tmp/keisei-tomd-cache).
/compose-solution discovery
Phase 3 prior-art sweep greps _primitives/ alongside _blocks/,
_manifests/, skills/, _bridges/, hooks/. If a user task involves
file-format parsing, the meta-composer surfaces tomd automatically —
reuse over rewrite (RULE "No Patching").