feat(skill): enhance add-telegram skill with Markdown rendering, file…

[kadaliao]

… downloads, and Linux/Docker guidance

• Update telegram.ts implementation with markdownToHtml() method (HTML parse mode with fallback to plain text) and document download support (≤10MB files saved to /workspace/group/uploads/)
• Document typing indicator interval pattern: stopTyping() must be called before sendMessage() so the indicator clears when the message arrives
• Add Linux/Docker section covering IPC directory permissions (mode 0o777/0o666 required when host runs as root and container runs as node user), session directory permissions, and systemd env var limitations
• Document ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL proxy auth support, including the agent-runner mapping to ANTHROPIC_API_KEY
• Replace TypeScript registration snippet with runnable CJS script using correct DB column name (trigger_pattern, not trigger)
• Expand troubleshooting: "Not logged in", typing indicator stuck, IPC permission errors, systemd credential configuration

Type of Change

• Skill - updates a skill in .claude/skills/
• Fix - bug fix or security fix to source code
• Simplification - reduces or simplifies source code

Description

For Skills

• I have not made any changes to source code
• My skill contains instructions for Claude to follow (not pre-built code)
• I tested this skill on a fresh clone

[TomGranot]

This PR has merge conflicts after PR #307 (skills engine + multi-channel infrastructure) was merged. Could you rebase your branch against the latest main? Thanks!

[TomGranot]

Has merge conflicts since #307 shipped a Telegram skill package. After rebasing, the enhancements (Markdown rendering, file downloads, Linux/Docker guidance) should be reconciled with the Telegram skill that's now in main.

[kadaliao]

Has merge conflicts since #307 shipped a Telegram skill package. After rebasing, the enhancements (Markdown rendering, file downloads, Linux/Docker guidance) should be reconciled with the Telegram skill that's now in main.

Done — rebased onto latest main and reconciled with the skill package from #307. Here's what's in the PR now:

SKILL.md — updated to the Phase 1–5 skills engine structure, keeping:

• Linux/Docker guidance (IPC/session directory permissions)
• Expanded troubleshooting (bot not responding, group privacy, chat ID)
• register-chat.cjs script with correct trigger_pattern column name

Skill package — add/src/channels/telegram.ts:

• markdownToHtml() converts Claude's Markdown output to Telegram HTML (<b>, <i>, <code>, <pre>, <a>)
• sendMessage() sends with parse_mode: 'HTML', falls back to plain text on parse errors
• File download support: documents ≤10MB saved to groups/{folder}/uploads/
• prefixAssistantName = false (Telegram bots already show their name)

Skill package — modify/src/index.ts:

• Typing indicator interval pattern: setInterval refreshes every 4s (Telegram's action expires after ~5s), stopTyping() called before sendMessage so the indicator clears immediately when output arrives

Branch is conflict-free and ready for re-review.

[kadaliao]

@TomGranot Please review this.

[Andy-NanoClaw-AI]

Hey @kadaliao 👋 Thanks for working on Telegram improvements — Markdown rendering and file support are great additions!

This work was superseded by the merged #83 (/add-telegram skill), which became the official Telegram integration. The codebase has evolved significantly since then, and this PR now has merge conflicts that make it difficult to apply cleanly.

We're adding Status: Pending Closure. If you'd like to revive these improvements, a fresh PR against main would be very welcome! 🙌

[kadaliao]

Squashed and force-pushed to kadaliao:dev — single clean commit on top of latest main.

Commit: f9c9e4a

Reviewer-friendly change summary by file:

Telegram channel implementation

• src/channels/telegram.ts

  • Adds a dedicated Telegram channel implementation for the current channel architecture.
  • Converts Claude-style Markdown into Telegram HTML — headings (# → <b>), bullets (- item → • item), bold, italic, strikethrough (~~), inline code, fenced code blocks, and [links](url).
  • Renders Markdown tables as CJK-aware ASCII art inside <pre> blocks (Telegram has no native table support).
  • Falls back to plain text if Telegram rejects HTML parsing.
  • Chunks long replies at Telegram's 4096-character limit.
  • Downloads Telegram photos and documents up to 20 MB into the group's uploads/ directory; preserves larger files as placeholders so context is not lost.
  • Normalizes Telegram @bot_username mentions into NanoClaw's trigger format.

• src/channels/telegram.test.ts

  • 55 unit tests covering: Markdown rendering, table rendering, HTML fallback, message chunking, mention translation, photo/document downloads, typing actions, and connection lifecycle.

• src/channels/index.ts

  • Registers the Telegram channel in the current self-registration barrel.

Response-state / UX behavior

• src/index.ts
  • Replaces one-shot typing with a heartbeat-style typing refresh (every 4s) while the agent is still working.
  • Stops typing immediately before sending output; resumes only if more work is still in flight.

Setup / operator workflow

• scripts/register-chat.cjs

  • Thin registration helper wrapping the existing setup register flow.

• docs/TELEGRAM.md

  • Telegram-specific setup and troubleshooting: Linux/macOS restart notes, privacy-mode guidance, file behavior, and common failure modes.

• .claude/skills/add-telegram/SKILL.md + manifest.yaml

  • Updated skill instructions: ensure the service is running before asking the user to send /chatid, preventing a common setup failure.
  • Adds grammy to the skill's dependency manifest.

Dependency alignment

• package.json / package-lock.json

  • Adds grammy for Telegram Bot API support.

• .env.example, README.md, README_zh.md

  • Adds TELEGRAM_BOT_TOKEN env var and pointer to Telegram setup docs.

Validation performed:

• npm run build ✅
• npm test ✅ (55 Telegram tests passing)

[cschmidt]

Hi @kadaliao — nice work on the file download and Markdown rendering!

I'm Claude Code (AI assistant) working with @cschmidt. We independently built file download support and submitted it as a PR against the Telegram channel fork (the current architecture for channel contributions): qwibitai/nanoclaw-telegram#7

That PR covers photos, documents, video, voice messages, and audio. It doesn't include Markdown rendering or typing indicator improvements (those are separate concerns handled locally via the skill system).

Just flagging the overlap in case it's useful for anyone tracking this feature area.