@hienlh/ppm 0.9.31 → 0.9.32

package/docs/project-roadmap.md

@@ -109,14 +109,15 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 
 ### v0.11.0 — "Intelligence" (Q3–Q4 2026)
 
-**Theme:** Event system + PPM's own AI layer. Hooks → Skills API → Clawbot dependency chain.
+**Theme:** Event system + PPM's own AI layer + Telegram bot. Hooks → Skills API → Clawbot dependency chain.
 
-| Feature | Priority | Description |
-|---------|----------|-------------|
-| **Hooks system** | High | Event hooks for PPM lifecycle (file save, git commit, chat message, etc.). Foundation for Skills API and deeper extension integration. |
-| **PPM Skills API** | High | Stable internal API for AI to control PPM: file.read/write/search, terminal.run, git.status/commit/diff, db.query, editor.open/goto, project.switch. Skills are the bridge between AI and PPM features. |
-| **Built-in Clawbot** | High | Lightweight AI agent built into PPM using Anthropic Messages API (not Agent SDK). Uses Skills API + MCP tools. Instant response, no external CLI deps. For quick tasks: file search, code explanation, simple refactors. |
-| **More providers** | Medium | Gemini CLI (Tier 2), OpenAI Codex (Tier 2), Tier 3 chat-only (any OpenAI-compatible API). Provider interface already clean from v0.9. |
+| Feature | Priority | Status | Description |
+|---------|----------|--------|-------------|
+| **Hooks system** | High | — | Event hooks for PPM lifecycle (file save, git commit, chat message, etc.). Foundation for Skills API and deeper extension integration. |
+| **PPM Skills API** | High | — | Stable internal API for AI to control PPM: file.read/write/search, terminal.run, git.status/commit/diff, db.query, editor.open/goto, project.switch. Skills are the bridge between AI and PPM features. |
+| **Telegram Bot (ClawBot)** | High | ✅ Done (v0.9.10) | Long-polling Telegram bot with session routing, FTS5 memory system, progressive message editing, pairing-based security. Routes through existing providers (Claude SDK, Cursor). No external bot infrastructure. |
+| **Built-in Clawbot** | High | — | Lightweight AI agent built into PPM using Anthropic Messages API (not Agent SDK). Uses Skills API + MCP tools. Instant response, no external CLI deps. For quick tasks: file search, code explanation, simple refactors. |
+| **More providers** | Medium | — | Gemini CLI (Tier 2), OpenAI Codex (Tier 2), Tier 3 chat-only (any OpenAI-compatible API). Provider interface already clean from v0.9. |
 
 **Built-in Clawbot — why it matters:**
 - Claude Agent SDK spawns subprocess — heavy, slow startup, requires CLI installed
@@ -124,6 +125,12 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 - Users can use Clawbot to create extensions → zero-friction extension authoring
 - Foundation for "AI creates extensions on demand" vision
 
+**Telegram Bot — why it matters:**
+- Extends PPM beyond the web UI → reach users on mobile, messaging apps
+- Long-polling avoids webhooks — simpler for self-hosted, no public URL needed
+- Paired devices enable secure multi-user access — owner controls who can use the bot
+- Persistent memory in FTS5 — bot learns conversation context over time
+
 ---
 
 ### v1.0.0 — "Production Ready" (Q4 2026)

package/docs/system-architecture.md

@@ -193,8 +193,14 @@ Tab IDs are deterministic: `{type}:{identifier}` (e.g., `editor:src/index.ts`, `
 | **AccountService** | Account CRUD, token encryption/decryption | getAccounts, createAccount, updateAccount, deleteAccount |
 | **AccountSelectorService** | Select active account based on config | getActiveAccount, setActiveAccount, selectByProject |
 | **UpgradeService** | Version checking, installation, self-replace signaling | checkForUpdate, applyUpgrade, getInstallMethod, compareSemver |
+| **ClawBotService** | Telegram bot orchestrator | start, stop, handleMessage, routeToChat |
+| **ClawBotTelegramService** | Telegram long-polling, message ops | getUpdates, sendMessage, editMessage, setTyping, handleCommands |
+| **ClawBotSessionService** | chatID → PPM sessionID mapping | mapSession, getSession, deleteSession |
+| **ClawBotMemoryService** | FTS5 memory persistence | saveMemory, recallMemories, decayMemories, searchByProject |
+| **ClawBotFormatterService** | Markdown → Telegram HTML + chunking | formatMarkdown, chunkMessage |
+| **ClawBotStreamerService** | ChatEvent → progressive Telegram edits | streamMessageEdits |
 
-**Key Files:** `src/services/*.service.ts`
+**Key Files:** `src/services/*.service.ts`, `src/services/clawbot/*.ts`
 
 ---
 
@@ -263,6 +269,63 @@ PPM supports multiple AI providers through a generic `AIProvider` interface and
 
 ---
 
+### ClawBot Service Layer (Telegram Bot Integration)
+**Component:** Telegram bot service + subsidiary services
+
+**Responsibilities:**
+- Receive Telegram messages via long-polling (no webhooks needed)
+- Route Telegram user (chatID) to PPM session with pairing-based security
+- Persist session state + conversation memory in SQLite (FTS5)
+- Stream AI responses back to Telegram with progressive message editing
+- Format responses as Telegram HTML with proper chunking (4096 char limit)
+
+**Architecture:**
+```
+Telegram → ClawBotTelegramService (polling) → ClawBotService (orchestrator)
+                                                    ↓
+                                            ClawBotSessionService (chatID→sessionID)
+                                            ClawBotMemoryService (FTS5 recall)
+                                            ChatService + ProviderRegistry
+                                            ClawBotStreamerService (ChatEvent→edits)
+                                            ClawBotFormatterService (Markdown→HTML)
+```
+
+**Services (src/services/clawbot/):**
+- **ClawBotService** — Lifecycle management (start/stop), message queue, routing logic
+- **ClawBotTelegramService** — Telegram Bot API wrapper (getUpdates long-polling, sendMessage, editMessage, setTyping, command handlers)
+- **ClawBotSessionService** — chatID ↔ PPM sessionID bidirectional mapping, session state tracking
+- **ClawBotMemoryService** — FTS5 persistent memory (save, recall with relevance, decay factor, supersede logic, cross-project search by name mention)
+- **ClawBotFormatterService** — Markdown → Telegram HTML conversion, message chunking (respects 4096 char limit), code block formatting
+- **ClawBotStreamerService** — ChatEvent async generator → progressive Telegram message edits (1s throttle for rate limiting)
+
+**Security Model:**
+- **Pairing System** — Replace allowlists with code-based pairing: User requests pairing → receives code → owner approves in web UI → chatID registered in `clawbot_paired_chats`
+- **Per-User Sessions** — Each Telegram chatID maps to isolated PPM session (no cross-user interference)
+- **bypassPermissions** — ClawBot bot runs headless, auto-approves tools (no manual approval flow)
+
+**Database Schema (v13):**
+- `clawbot_sessions` — chatID (PK), sessionID (FK chat_sessions), pairedAt, lastUsed
+- `clawbot_memories` — id (PK), sessionID (FK), content (text), role (user|assistant), created, decay_factor (FTS5 full-text index)
+- `clawbot_paired_chats` — chatID (PK), pairingCode (unique, 6 chars), approvedAt, approvedBy (user ID)
+
+**Key Design Decisions:**
+1. **Long-polling** — No webhooks = no public URL required, simpler for self-hosted
+2. **Message queue** — Concurrent Telegram messages queued FIFO, prevents race conditions
+3. **Progressive edits** — Edit same message for long responses, reduce Telegram API calls, better UX
+4. **Memory system** — Hybrid extraction (AI primary + regex fallback), supports cross-project search by project name mention
+5. **Config reuse** — Shares existing Telegram bot_token with notifications, separate ClawBotConfig section
+6. **Session tagging** — [Claw] prefix visible in web UI without schema changes, robot icon for identification
+
+**Settings Endpoints:**
+- `GET /api/settings/clawbot` — Fetch config (enabled, bot token, default project, system prompt, debounce, display toggles)
+- `PUT /api/settings/clawbot` — Update config
+- `GET /api/clawbot/paired-chats` — List paired Telegram chatIDs
+- `POST /api/clawbot/pairing` — Request pairing code (returns code)
+- `POST /api/clawbot/pairing/:code/approve` — Approve pairing code (owner only)
+- `DELETE /api/clawbot/paired-chats/:chatId` — Revoke pairing
+
+---
+
 ### Data Access Layer (SQLite + Filesystem + Git)
 **Components:** SQLite via bun:sqlite, direct filesystem access, simple-git wrapper
 
@@ -274,7 +337,7 @@ PPM supports multiple AI providers through a generic `AIProvider` interface and
 - Enforce security (no parent directory access)
 
 **Key Patterns:**
-- SQLite: WAL mode, foreign keys, lazy init, schema v10 (10 tables: config, connections, accounts, usage_history, session_logs, push_subscriptions, session_map, table_metadata, session_logs, workspace_state)
+- SQLite: WAL mode, foreign keys, lazy init, schema v13 (13 tables: config, connections, accounts, usage_history, session_logs, push_subscriptions, session_map, table_metadata, workspace_state, extension_storage, mcp_servers, clawbot_sessions, clawbot_memories, clawbot_paired_chats)
 - Path validation: `projectPath/relativePath` only, reject `..`
 - Caching: Directory trees cached with TTL
 - Error handling: Descriptive messages (file not found, permission denied)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.31",
+  "version": "0.9.32",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/server/index.ts

@@ -477,5 +477,12 @@ if (process.argv.includes("__serve__")) {
     console.error("[ExtService] Startup error:", e);
   });
 
+  // Start ClawBot Telegram poller (if enabled)
+  import("../services/clawbot/clawbot-service.ts")
+    .then(({ clawbotService }) => clawbotService.start())
+    .catch((e) => {
+      console.error("[clawbot] Startup error:", e);
+    });
+
   console.log(`Server child ready on port ${port}`);
 }

package/src/server/routes/proxy.ts

@@ -57,6 +57,21 @@ proxyRoutes.post("/v1/messages", async (c) => {
   return proxyService.forward("/v1/messages", "POST", headers, body);
 });
 
+/** POST /proxy/v1/chat/completions — OpenAI-compatible chat completions proxy */
+proxyRoutes.post("/v1/chat/completions", async (c) => {
+  if (!proxyService.isEnabled()) {
+    return c.json({ error: { message: "Proxy is disabled", type: "server_error" } }, 503);
+  }
+
+  const authHeader = c.req.header("authorization") || c.req.header("x-api-key");
+  if (!validateProxyAuth(authHeader)) {
+    return c.json({ error: { message: "Invalid proxy auth key", type: "authentication_error" } }, 401);
+  }
+
+  const body = await c.req.text();
+  return proxyService.forwardOpenAi(body);
+});
+
 /** POST /proxy/v1/messages/count_tokens — token counting proxy */
 proxyRoutes.post("/v1/messages/count_tokens", async (c) => {
   if (!proxyService.isEnabled()) {

package/src/server/routes/settings.ts

@@ -1,12 +1,14 @@
 import { Hono } from "hono";
 import { configService } from "../../services/config.service.ts";
-import { getConfigValue, setConfigValue } from "../../services/db.service.ts";
+import { getConfigValue, setConfigValue, listPairedChats, getPairingByCode, approvePairing, revokePairing } from "../../services/db.service.ts";
 import {
   validateAIProviderConfig,
   validateDefaultProvider,
   VALID_PROVIDERS,
+  DEFAULT_CONFIG,
   type AIProviderConfig,
   type TelegramConfig,
+  type ClawBotConfig,
   type ThemeConfig,
 } from "../../types/config.ts";
 import { ok, err } from "../../types/api.ts";
@@ -292,8 +294,10 @@ async function buildProxyResponse() {
     authKey: proxyService.getAuthKey() ?? null,
     requestCount: proxyService.getRequestCount(),
     localEndpoint: `${localOrigin}/proxy/v1/messages`,
+    localOpenAiEndpoint: `${localOrigin}/proxy/v1/chat/completions`,
     tunnelUrl: tunnelUrl ?? null,
     proxyEndpoint: tunnelUrl ? `${tunnelUrl}/proxy/v1/messages` : null,
+    openAiEndpoint: tunnelUrl ? `${tunnelUrl}/proxy/v1/chat/completions` : null,
   };
 }
 
@@ -314,3 +318,72 @@ settingsRoutes.put("/proxy", async (c) => {
     return c.json(err((e as Error).message), 400);
   }
 });
+
+// ── ClawBot ─────────────────────────────────────────────────────
+
+/** GET /settings/clawbot — return current clawbot config */
+settingsRoutes.get("/clawbot", (c) => {
+  const config = configService.get("clawbot") as ClawBotConfig | undefined;
+  if (!config) return c.json(ok(DEFAULT_CONFIG.clawbot));
+  return c.json(ok(config));
+});
+
+/** PUT /settings/clawbot — update clawbot config */
+settingsRoutes.put("/clawbot", async (c) => {
+  try {
+    const body = await c.req.json<Partial<ClawBotConfig>>();
+    const current = (configService.get("clawbot") as ClawBotConfig | undefined)
+      ?? structuredClone(DEFAULT_CONFIG.clawbot!);
+    const updated: ClawBotConfig = { ...current, ...body };
+
+    if (updated.debounce_ms < 0 || updated.debounce_ms > 30000) {
+      return c.json(err("debounce_ms must be 0-30000"), 400);
+    }
+
+    configService.set("clawbot", updated);
+    configService.save();
+
+    // Restart clawbot if running state changed
+    try {
+      const { clawbotService } = await import("../../services/clawbot/clawbot-service.ts");
+      if (updated.enabled && !clawbotService.isRunning) {
+        await clawbotService.start();
+      } else if (!updated.enabled && clawbotService.isRunning) {
+        clawbotService.stop();
+      }
+    } catch { /* ClawBot module not loaded yet — OK */ }
+
+    return c.json(ok(updated));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** GET /settings/clawbot/paired — list paired devices */
+settingsRoutes.get("/clawbot/paired", (c) => {
+  return c.json(ok(listPairedChats()));
+});
+
+/** POST /settings/clawbot/paired/approve — approve pairing by code */
+settingsRoutes.post("/clawbot/paired/approve", async (c) => {
+  try {
+    const { code } = await c.req.json<{ code: string }>();
+    const pairing = getPairingByCode(code);
+    if (!pairing) return c.json(err("Invalid pairing code"), 404);
+    approvePairing(pairing.telegram_chat_id);
+    // Notify user on Telegram
+    try {
+      const { clawbotService } = await import("../../services/clawbot/clawbot-service.ts");
+      await clawbotService.notifyPairingApproved(pairing.telegram_chat_id);
+    } catch { /* OK */ }
+    return c.json(ok({ approved: pairing.telegram_chat_id }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** DELETE /settings/clawbot/paired/:chatId — revoke pairing */
+settingsRoutes.delete("/clawbot/paired/:chatId", (c) => {
+  revokePairing(c.req.param("chatId"));
+  return c.json(ok({ revoked: true }));
+});

package/src/services/clawbot/clawbot-formatter.ts

@@ -0,0 +1,88 @@
+const MAX_MESSAGE_LENGTH = 4096;
+
+/** Escape HTML special chars for Telegram HTML parse mode */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Convert Markdown to Telegram-compatible HTML.
+ * Handles: **bold**, *italic*, `code`, ```pre```, [links](url), ~~strikethrough~~
+ * Does NOT handle nested formatting (Telegram limitation).
+ */
+export function markdownToTelegramHtml(md: string): string {
+  let html = md;
+
+  // Code blocks first (prevent inner processing)
+  html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
+    const langAttr = lang ? ` class="language-${escapeHtml(lang)}"` : "";
+    return `<pre><code${langAttr}>${escapeHtml(code.trimEnd())}</code></pre>`;
+  });
+
+  // Inline code: `code` → <code>code</code>
+  html = html.replace(/`([^`\n]+)`/g, (_match, code) => {
+    return `<code>${escapeHtml(code)}</code>`;
+  });
+
+  // Bold: **text** → <b>text</b>
+  html = html.replace(/\*\*(.+?)\*\*/g, "<b>$1</b>");
+
+  // Italic: *text* → <i>text</i>
+  html = html.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, "<i>$1</i>");
+
+  // Strikethrough: ~~text~~ → <s>text</s>
+  html = html.replace(/~~(.+?)~~/g, "<s>$1</s>");
+
+  // Links: [text](url) → <a href="url">text</a>
+  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  return html;
+}
+
+/**
+ * Split text into chunks that fit Telegram's 4096 char limit.
+ * Tries to break at newlines, falling back to word boundaries.
+ */
+export function chunkMessage(text: string, maxLen = MAX_MESSAGE_LENGTH): string[] {
+  if (text.length <= maxLen) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLen) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let breakAt = -1;
+    const searchWindow = remaining.slice(0, maxLen);
+
+    // Try double newline
+    breakAt = searchWindow.lastIndexOf("\n\n");
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = searchWindow.lastIndexOf("\n");
+    }
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = searchWindow.lastIndexOf(" ");
+    }
+    if (breakAt === -1 || breakAt < maxLen * 0.3) {
+      breakAt = maxLen;
+    }
+
+    chunks.push(remaining.slice(0, breakAt));
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+
+  return chunks;
+}
+
+/** Truncate text for preview (e.g. session titles), adding ellipsis */
+export function truncateForPreview(text: string, maxLen = 200): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "\u2026";
+}