clearclaw 0.7.0 → 0.8.0

package/README.md

@@ -17,7 +17,7 @@ ClearClaw reuses what the CLI already has:
 
 ## What It Does
 
-- Routes messages between your phone and your coding agent (Telegram today, Slack planned)
+- Routes messages between your phone and your coding agent through Telegram or Slack
 - Permission prompts with diffs, tool status, and feedback — like the terminal, on your phone
 - Maps chat groups to project workspaces — each group = a working directory
 - Personal assistant workspace for non-project conversations
@@ -33,19 +33,65 @@ ClearClaw reuses what the CLI already has:
 ## Quick Start
 
 ```bash
-export TELEGRAM_BOT_TOKEN="your-bot-token"
-export ALLOWED_USER_IDS="tg:your-telegram-id"
-
-npx clearclaw
+npm install -g clearclaw
+clearclaw setup
+clearclaw daemon
 ```
 
-Or install globally: `npm install -g clearclaw`
+Setup saves the channel tokens and default engine, then asks you to DM the bot and approve its pairing code. The platform supplies your user and chat IDs; you do not need to copy them into environment variables. Additional pairing requests can be approved with `clearclaw approve <code>`.
+
+Home is created automatically and connects to the approved DM. Start chatting immediately. Ask from home or another workspace to create a project and workspace together. If you choose a manual chat, create the group and send `/connect <workspace>` there (Slack: `/cc connect <workspace>`).
+
+Existing environment-based installations remain supported: channel token variables and `ALLOWED_USER_IDS` override saved configuration. An authorized user's first root DM binds an unbound home. Existing bindings are preserved.
+
+Send `/recap` (Slack: `/cc recap`) to replay the current session's last three prompts and their replies, including any reply still in progress. It reads history from the workspace's engine, so it also includes work done in the CLI. Use `/resume` separately when you want to select a different session.
+If the engine locks history during an active turn, retry after that turn finishes.
 
 Optional: `PERMISSION_MODE` (`default` | `acceptEdits` | `bypassPermissions` | `plan`), `CLEARCLAW_HOME` (default `~/.clearclaw`).
 
+### Engine executable and config paths
+
+Setup stores the selected engine's resolved CLI executable in `~/.clearclaw/config.json` as `engines[].path`. Claude Code passes this path to the Agent SDK. Kiro runs this path with the `acp` argument. Codex starts ClearClaw's pinned, patched `codex-acp` adapter through Node and passes the configured Codex CLI path to it as `CODEX_PATH`.
+
+For Codex, setup prefers an installed `codex` CLI; if none is on `PATH`, it omits the override and uses the bundled executable.
+
+Without a configured override, Kiro resolves `kiro-cli` from `PATH`. Codex preserves an inherited `CODEX_PATH`, otherwise its adapter uses the bundled Codex executable.
+
+Executable and config paths belong to the engine and apply wherever that engine is used. Set optional `engines[].configPath` to an absolute settings-file path for Claude Code or Codex:
+
+```json
+{
+  "engines": [
+    { "name": "claude-code", "default": true, "configPath": "/path/to/dotfiles/claude/settings.json" },
+    { "name": "codex", "configPath": "/path/to/dotfiles/codex/config.json" }
+  ]
+}
+```
+
+Keep any existing `path` overrides when adding `configPath`. No shell export or copy to the agent's home directory is required for these files.
+
+- **Claude Code:** passes the file through the SDK's `settings` option (`--settings`). User, project, and local settings sources remain enabled. Explicit settings override conflicting scalar values in those sources; most lists merge under Claude's native rules. Existing user settings and symlinks remain the user's choice.
+- **Codex:** reads the JSON object at each adapter launch and supplies it as `CODEX_CONFIG`, adding ClearClaw's assembled developer instructions on top. An explicit file replaces inherited `CODEX_CONFIG` input; omitting `configPath` preserves environment-based behavior. Missing, malformed, or non-object JSON fails the launch. The adapter passes these values as thread config; native Codex still owns its normal configuration layers and startup plugin catalog.
+
+  This file carries thread settings only (`model`, `model_providers`, `mcp_servers`, `sandbox_*`, and similar). It cannot carry `marketplaces` or `plugins`: those are Codex CLI installation state, applied long before a thread exists, so declaring them installs nothing and an uninstalled marketplace fails every thread. ClearClaw rejects both keys at load and names the `codex plugin` commands that do install them. Skills need no declaration at all, since Codex reads `~/.agents/skills` and `<cwd>/.agents/skills` natively.
+
+Restart the daemon after changing `engines` entries. File contents are read again on subsequent launches. Kiro does not support `configPath`. This does not add named-profile support or change native CLI launches outside ClearClaw.
+
+For Slack, setup saves the bot and app tokens; environment-based installs can use
+`SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, and Slack-prefixed `ALLOWED_USER_IDS`. Private peer-channel spawning
+also requires the `groups:write` bot-token scope; reinstall the app after adding
+the scope. Shared project sidebar sections require a paid Slack plan, the
+`usergroups:read` and `usergroups:write` bot-token scopes, and workspace User
+Group permissions set to allow everyone to manage them. Reinstall the app after
+changing scopes.
+
+Telegram peer topics require Topics to be enabled manually on a supergroup and
+the bot to be an admin with Manage Topics. Private-chat topics require Threaded
+Mode to be enabled for the bot in BotFather.
+
 ## Architecture
 
-Two interfaces keep the core thin: **Channels** (Telegram, Slack, ...) handle messaging, **Engines** (Claude Code, Codex, Kiro, ...) handle the agent. The orchestrator routes between them — adding a channel or engine means adding a file. Details in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+Two interfaces keep the core thin: **Channels** (Telegram, Slack, ...) handle messaging, **Engines** (Claude Code, Codex, Kiro, ...) handle the agent. The orchestrator routes between them — adding a channel or engine means adding a file. Details in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Project lifecycle contracts and design decisions are in [Projects and peer spawning](docs/specs/peer-spawning.md).
 
 ## Prior Art
 

package/dist/channel/slack.d.ts

@@ -2,20 +2,31 @@ import { EventEmitter } from "node:events";
 import type { Channel, Button, ButtonResponse, SendFileOpts, MessageOpts, UserInfo } from "../types.js";
 export declare class SlackChannel extends EventEmitter implements Channel {
     name: string;
+    statusMaxLength: number;
     private static readonly EMOJI_TO_SLACK;
     private app;
     private botToken;
+    private appToken;
     private botUserId;
     private isAuthorized;
+    private authorizedUserIds;
     private onUnauthorizedDM?;
     private pendingButtonCallbacks;
     private pendingModalCallbacks;
     private typingMessageTs;
+    private typingTimers;
     private userNameCache;
-    constructor(botToken: string, appToken: string, isAuthorized: (userId: string) => boolean, onUnauthorizedDM?: (chatId: string, user: UserInfo) => void);
+    constructor(botToken: string, appToken: string, isAuthorized: (userId: string) => boolean, onUnauthorizedDM?: (chatId: string, user: UserInfo) => void, authorizedUserIds?: () => string[]);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
+    /** Slack DM conversation ids start with D; channels start with C or G. */
+    isRootDM(chatId: string, userId: string): boolean;
+    groupProjectChat(projectName: string, chatId: string): Promise<string | undefined>;
+    createProjectChat(_projectName: string, _anchor: string, title: string): Promise<string>;
+    closeProjectChat(chatId: string, projectName?: string): Promise<void>;
+    /** Apply one lifecycle change to live Slack preferences; never restore a config snapshot. */
+    private updateProjectSection;
     sendMessage(chatId: string, text: string, opts?: MessageOpts): Promise<string[]>;
     sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
     editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
@@ -23,10 +34,16 @@ export declare class SlackChannel extends EventEmitter implements Channel {
     pinMessage(chatId: string, handle: string): Promise<void>;
     unpinAllMessages(chatId: string): Promise<void>;
     updateStatus(chatId: string, text: string): Promise<void>;
+    /**
+     * Stop refreshing a placeholder. Every path that drops the ts must call this,
+     * or the timer keeps editing a message that is gone.
+     */
+    private stopTypingHeartbeat;
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
     sendFile(chatId: string, buffer: Buffer, filename: string, opts?: SendFileOpts): Promise<void>;
     reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;
     private slackId;
+    private authorizedSlackUsers;
     /** Download a file from Slack using bot token auth. */
     private downloadFile;
     private resolveUserName;

package/dist/channel/slack.js

@@ -1,9 +1,10 @@
+import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { App, LogLevel } from "@slack/bolt";
-import { slackifyMarkdown } from "slackify-markdown";
 import log from "../logger.js";
 export class SlackChannel extends EventEmitter {
     name = "slack";
+    statusMaxLength = 250;
     static EMOJI_TO_SLACK = {
         "👍": "+1", "👎": "-1", "❤️": "heart", "🔥": "fire",
         "😂": "joy", "🎉": "tada", "✅": "white_check_mark", "🚀": "rocket",
@@ -12,23 +13,28 @@ export class SlackChannel extends EventEmitter {
     };
     app;
     botToken;
+    appToken;
     botUserId;
     isAuthorized;
+    authorizedUserIds;
     onUnauthorizedDM;
     pendingButtonCallbacks = new Map(); // actionId → resolve
     pendingModalCallbacks = new Map(); // modal callbackId → resolve
     typingMessageTs = new Map(); // chatId → ts of bot's "typing…" placeholder
+    typingTimers = new Map(); // chatId → placeholder refresher
     userNameCache = new Map();
-    constructor(botToken, appToken, isAuthorized, onUnauthorizedDM) {
+    constructor(botToken, appToken, isAuthorized, onUnauthorizedDM, authorizedUserIds = () => []) {
         super();
         this.botToken = botToken;
+        this.appToken = appToken;
         this.isAuthorized = isAuthorized;
+        this.authorizedUserIds = authorizedUserIds;
         this.onUnauthorizedDM = onUnauthorizedDM;
-        this.app = new App({
-            token: botToken, appToken, socketMode: true, logLevel: LogLevel.ERROR,
-        });
     }
     async connect() {
+        this.app = new App({
+            token: this.botToken, appToken: this.appToken, socketMode: true, logLevel: LogLevel.ERROR,
+        });
         this.app.event("message", async ({ event }) => {
             const subtype = event.subtype;
             // Suppress topic-change system messages from our setTopic calls
@@ -96,7 +102,7 @@ export class SlackChannel extends EventEmitter {
             this.emit("message", {
                 chatId,
                 chatType,
-                user: { id: prefixedId, name: userName ?? userId },
+                origin: { kind: "user", user: { id: prefixedId, name: userName ?? userId } },
                 text: msg.text ?? "",
                 messageId: msg.ts,
                 replyTo,
@@ -127,7 +133,7 @@ export class SlackChannel extends EventEmitter {
             this.emit("message", {
                 chatId,
                 chatType,
-                user: { id: `slack:${userId}`, name: userName ?? userId },
+                origin: { kind: "user", user: { id: `slack:${userId}`, name: userName ?? userId } },
                 text: `/${subcommand}`,
             });
         });
@@ -154,6 +160,7 @@ export class SlackChannel extends EventEmitter {
     async disconnect() {
         // Delete lingering typing placeholder messages
         for (const [chatId, ts] of this.typingMessageTs) {
+            this.stopTypingHeartbeat(chatId);
             try {
                 await this.app.client.chat.delete({ channel: this.slackId(chatId), ts });
             }
@@ -163,6 +170,117 @@ export class SlackChannel extends EventEmitter {
         await this.app.stop();
     }
     ownsId(chatId) { return chatId.startsWith("slack:"); }
+    /** Slack DM conversation ids start with D; channels start with C or G. */
+    isRootDM(chatId, userId) {
+        return /^slack:D[A-Z0-9]+$/.test(chatId) && userId.startsWith("slack:");
+    }
+    async groupProjectChat(projectName, chatId) {
+        return this.updateProjectSection(projectName, chatId, "attach");
+    }
+    async createProjectChat(_projectName, _anchor, title) {
+        const users = this.authorizedSlackUsers();
+        if (users.length === 0) {
+            throw new Error("Cannot create Slack peer: no authorized Slack users to invite");
+        }
+        const result = await this.app.client.conversations.create({
+            name: slackChannelName(title),
+            is_private: true,
+        });
+        const channel = result.channel?.id;
+        if (!channel)
+            throw new Error("Slack created a peer channel without returning its ID");
+        try {
+            await this.app.client.conversations.invite({
+                channel,
+                users: users.join(","),
+            });
+        }
+        catch (err) {
+            await this.app.client.conversations.archive({ channel }).catch((archiveErr) => {
+                log.warn({ err: archiveErr }, "[channel] failed to archive Slack peer after invite failure");
+            });
+            throw err;
+        }
+        return `slack:${channel}`;
+    }
+    async closeProjectChat(chatId, projectName) {
+        try {
+            await this.app.client.conversations.archive({
+                channel: this.slackId(chatId),
+            });
+        }
+        catch (err) {
+            const code = slackErrorCode(err);
+            if (code !== "already_archived" && code !== "channel_not_found")
+                throw err;
+        }
+        if (projectName)
+            await this.updateProjectSection(projectName, chatId, "remove");
+    }
+    /** Apply one lifecycle change to live Slack preferences; never restore a config snapshot. */
+    async updateProjectSection(projectName, chatId, action) {
+        const channel = this.slackId(chatId);
+        // A DM cannot belong to a sidebar section; its Project groups its channel peers instead.
+        if (!channel.startsWith("C") && !channel.startsWith("G"))
+            return;
+        try {
+            const result = await this.app.client.apiCall("usergroups.list", {
+                include_disabled: true,
+            });
+            const groups = result.usergroups ?? [];
+            const description = slackUserGroupDescription(projectName);
+            // The marker survives manual name/handle changes. Without it, leave the group alone.
+            const group = groups.find((candidate) => candidate.description === description);
+            if (group) {
+                if (!group.id || group.date_delete)
+                    return;
+                const current = [...new Set([...(group.prefs?.channels ?? []), ...(group.prefs?.groups ?? [])])];
+                const channels = action === "remove"
+                    ? current.filter((id) => id !== channel)
+                    : [...new Set([...current, channel])];
+                if (channels.length === current.length && channels.every((id, i) => id === current[i]))
+                    return;
+                await this.app.client.apiCall("usergroups.update", {
+                    usergroup: group.id,
+                    channels: channels.join(","),
+                });
+                return;
+            }
+            // No owned group means this Project was never sectioned — attaching creates it. A group the
+            // user deleted is caught by the date_delete branch above, so this never resurrects one.
+            if (action === "remove")
+                return;
+            const users = this.authorizedSlackUsers();
+            if (users.length === 0)
+                throw new Error("Cannot create Slack project section: no authorized Slack users");
+            const baseHandle = slackUserGroupHandle(projectName);
+            const handle = groups.some((candidate) => candidate.handle === baseHandle)
+                ? slackUserGroupCollisionHandle(projectName)
+                : baseHandle;
+            if (groups.some((candidate) => candidate.handle === handle)) {
+                throw new Error(`Slack User Group handle "${handle}" is owned by another group`);
+            }
+            const created = await this.app.client.apiCall("usergroups.create", {
+                name: projectName,
+                handle,
+                description,
+                channels: channel,
+                enable_section: true,
+            });
+            if (!created.usergroup?.id)
+                throw new Error("Slack created a project section without returning its User Group ID");
+            await this.app.client.apiCall("usergroups.users.update", {
+                usergroup: created.usergroup.id,
+                users: users.join(","),
+            });
+        }
+        catch (err) {
+            log.warn({ err }, "[channel] failed to %s Slack project section for %s", action, projectName);
+            const reason = slackErrorCode(err) ?? (err instanceof Error ? err.message : String(err));
+            return `Slack could not ${action} the "${projectName}" sidebar section: ${reason}.`
+                + (SECTION_HINTS[reason] ? ` ${SECTION_HINTS[reason]}` : "");
+        }
+    }
     async sendMessage(chatId, text, opts) {
         const channel = this.slackId(chatId);
         const chunks = splitMessage(text);
@@ -175,7 +293,7 @@ export class SlackChannel extends EventEmitter {
                 const r = await this.app.client.chat.postMessage({ channel, text: chunk, ...extra });
                 return r.ts;
             }
-            const blocks = mrkdwnBlocks(chunk);
+            const blocks = markdownBlock(chunk);
             try {
                 const r = await this.app.client.chat.postMessage({ channel, text: chunk, blocks, ...extra });
                 return r.ts;
@@ -190,6 +308,7 @@ export class SlackChannel extends EventEmitter {
         const consumeTyping = !threadTs && opts?.consumeTyping !== false;
         const typingTs = consumeTyping ? this.typingMessageTs.get(chatId) : undefined;
         if (typingTs && chunks.length > 0) {
+            this.stopTypingHeartbeat(chatId);
             this.typingMessageTs.delete(chatId);
             const firstChunk = chunks.shift();
             if (plain) {
@@ -204,7 +323,7 @@ export class SlackChannel extends EventEmitter {
                 }
             }
             else {
-                const blocks = mrkdwnBlocks(firstChunk);
+                const blocks = markdownBlock(firstChunk);
                 try {
                     await this.app.client.chat.update({
                         channel, ts: typingTs, text: firstChunk, blocks,
@@ -237,7 +356,7 @@ export class SlackChannel extends EventEmitter {
             }
         }
         const blocks = [
-            mrkdwnBlocks(splitMessage(text)[0])[0],
+            markdownBlock(splitMessage(text)[0])[0],
             {
                 type: "actions",
                 elements: actionEntries.map(({ btn, actionId }) => ({
@@ -342,7 +461,7 @@ export class SlackChannel extends EventEmitter {
                 channel: this.slackId(chatId),
                 ts: handle,
                 text: chunk,
-                blocks: mrkdwnBlocks(chunk),
+                blocks: markdownBlock(chunk),
             });
         }
     }
@@ -380,6 +499,17 @@ export class SlackChannel extends EventEmitter {
             topic: text,
         });
     }
+    /**
+     * Stop refreshing a placeholder. Every path that drops the ts must call this,
+     * or the timer keeps editing a message that is gone.
+     */
+    stopTypingHeartbeat(chatId) {
+        const timer = this.typingTimers.get(chatId);
+        if (timer) {
+            clearInterval(timer);
+            this.typingTimers.delete(chatId);
+        }
+    }
     async setTyping(chatId, isTyping) {
         const channel = this.slackId(chatId);
         if (isTyping) {
@@ -387,15 +517,29 @@ export class SlackChannel extends EventEmitter {
                 return;
             try {
                 const result = await this.app.client.chat.postMessage({
-                    channel, text: "_typing…_",
+                    channel, text: typingText(0),
                 });
-                if (result.ts)
-                    this.typingMessageTs.set(chatId, result.ts);
+                if (!result.ts)
+                    return;
+                const ts = result.ts;
+                this.typingMessageTs.set(chatId, ts);
+                // Slack has no typing indicator for bots, so this placeholder stands in for one.
+                // Telegram's real indicator expires unless refreshed, which makes a dead process
+                // visibly stop typing; a posted message has no such property. Refreshing it with a
+                // running clock restores that signal: if the clock stops, so did the engine.
+                const startedAt = Date.now();
+                const timer = setInterval(() => {
+                    this.app.client.chat.update({
+                        channel, ts, text: typingText(Date.now() - startedAt),
+                    }).catch(() => { });
+                }, TYPING_REFRESH_MS);
+                this.typingTimers.set(chatId, timer);
             }
             catch { /* best-effort */ }
         }
         else {
             // Delete placeholder if it wasn't consumed by sendMessage
+            this.stopTypingHeartbeat(chatId);
             const ts = this.typingMessageTs.get(chatId);
             if (ts) {
                 this.typingMessageTs.delete(chatId);
@@ -435,6 +579,12 @@ export class SlackChannel extends EventEmitter {
     slackId(chatId) {
         return chatId.replace(/^slack:/, "");
     }
+    authorizedSlackUsers() {
+        return [...new Set(this.authorizedUserIds()
+                .filter((id) => id.startsWith("slack:"))
+                .map((id) => id.slice("slack:".length))
+                .filter(Boolean))];
+    }
     /** Download a file from Slack using bot token auth. */
     async downloadFile(url) {
         const resp = await fetch(url, {
@@ -487,20 +637,70 @@ export class SlackChannel extends EventEmitter {
         }
     }
 }
-function mrkdwnBlocks(text) {
-    let rendered;
-    try {
-        rendered = slackifyMarkdown(text);
-    }
-    catch (err) {
-        log.warn({ err }, "[channel] slackifyMarkdown failed, sending raw text");
-        rendered = text;
-    }
-    return [{ type: "section", text: { type: "mrkdwn", text: rendered } }];
+// Slack's markdown block renders standard markdown (headers, lists, tables) natively:
+// Slack owns the translation, so we hand it the raw markdown with no pre-conversion.
+function markdownBlock(text) {
+    return [{ type: "markdown", text }];
+}
+// The markdown block caps at 12,000 chars. We split at this limit so each chunk
+// fits the block; the text fallback (notification preview) can safely be longer.
+const MAX_TEXT = 12000;
+function slackChannelName(title) {
+    const name = title
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .slice(0, 80)
+        .replace(/[-_]+$/g, "");
+    if (!name)
+        throw new Error(`Cannot derive a valid Slack channel name from "${title}"`);
+    return name;
+}
+const TYPING_REFRESH_MS = 5000;
+/** Elapsed time makes the placeholder a liveness signal: a stopped clock means a stopped engine. */
+function typingText(elapsedMs) {
+    const seconds = Math.floor(elapsedMs / 1000);
+    if (seconds < 1)
+        return "_typing…_";
+    const label = seconds < 60
+        ? `${seconds}s`
+        : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+    return `_typing… ${label}_`;
+}
+function slackUserGroupHandle(projectName) {
+    const slug = slackChannelName(projectName)
+        .slice(0, 77)
+        .replace(/[-_]+$/g, "");
+    return `cc-${slug}`;
+}
+function slackUserGroupCollisionHandle(projectName) {
+    const hash = createHash("sha256").update(projectName).digest("hex").slice(0, 6);
+    const slug = slackChannelName(projectName)
+        .slice(0, 70)
+        .replace(/[-_]+$/g, "");
+    return `cc-${slug}-${hash}`;
+}
+function slackUserGroupDescription(projectName) {
+    const hash = createHash("sha256").update(projectName).digest("hex").slice(0, 16);
+    return `Managed by ClearClaw (${hash})`;
+}
+// Sidebar sections fail for reasons no code change can fix, so name the fix instead of the code.
+const SECTION_HINTS = {
+    paid_teams_only: "Slack User Groups need a paid plan.",
+    missing_scope: "Grant the app the usergroups:read and usergroups:write scopes and reinstall it.",
+    permission_denied: "Allow the app to manage User Groups in Workspace settings → Permissions.",
+};
+function slackErrorCode(err) {
+    if (typeof err !== "object" || err === null || !("data" in err))
+        return undefined;
+    const data = err.data;
+    if (typeof data !== "object" || data === null || !("error" in data))
+        return undefined;
+    const code = data.error;
+    return typeof code === "string" ? code : undefined;
 }
-// Block Kit section.text has a 3000 char limit — the tightest Slack constraint.
-// We split at this limit so each chunk fits both the text fallback and the block.
-const MAX_TEXT = 3000;
 function splitMessage(text) {
     if (text.length <= MAX_TEXT)
         return [text];

package/dist/channel/telegram.d.ts

@@ -10,15 +10,28 @@ export declare class TelegramChannel extends EventEmitter implements Channel {
     private statusHandles;
     private pendingCallbacks;
     private pendingTextResolvers;
+    private botUsername?;
     constructor(botToken: string, isAuthorized: (userId: string) => boolean, onUnauthorizedDM?: (chatId: string, user: UserInfo) => void);
+    /**
+     * Strip the `@<botUsername>` suffix Telegram appends to commands in group
+     * chats (`/context@mybot args` → `/context args`), so downstream command
+     * handling — ClearClaw's own `/new` etc. and slash-command pass-through —
+     * sees the bare `/command`. No-op for non-command text and in DMs (no suffix).
+     * Telegram usernames are `[A-Za-z0-9_]`, so they need no regex escaping.
+     */
+    private stripCommandMention;
+    private telegramCall;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
+    /** A private chat is the user's own id; a ":thread" suffix means a topic inside it. */
+    isRootDM(chatId: string, userId: string): boolean;
     sendMessage(chatId: string, text: string, opts?: MessageOpts): Promise<string[]>;
     sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
     editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
     deleteMessage(chatId: string, handle: string): Promise<void>;
     pinMessage(chatId: string, handle: string): Promise<void>;
+    /** Unpin everything in this chat's scope: the forum topic for a topic chat, else the whole chat. */
     unpinAllMessages(chatId: string): Promise<void>;
     updateStatus(chatId: string, text: string): Promise<void>;
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
@@ -32,7 +45,13 @@ export declare class TelegramChannel extends EventEmitter implements Channel {
     private handleFileMessage;
     sendFile(chatId: string, buffer: Buffer, filename: string, opts?: SendFileOpts): Promise<void>;
     reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;
+    createProjectChat(projectName: string, anchor: string, title: string): Promise<string>;
+    closeProjectChat(chatId: string): Promise<void>;
+    private validateProjectChat;
     /** Download a Telegram file by file_id, returning the raw buffer. */
     private downloadFile;
+    /** "tg:123" → 123; "tg:123:45" (forum topic) → 123 */
     private numericId;
+    /** Topic part of a composite chat id, as spreadable send options. */
+    private threadOpts;
 }