@chrysb/alphaclaw 0.1.25 → 0.2.1

package/bin/alphaclaw.js

@@ -5,17 +5,59 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { execSync } = require("child_process");
+const { buildSecretReplacements } = require("../lib/server/helpers");
 
 // ---------------------------------------------------------------------------
 // Parse CLI flags
 // ---------------------------------------------------------------------------
 
 const args = process.argv.slice(2);
-const command = args.find((a) => !a.startsWith("-"));
 
-const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+const flagValue = (argv, ...flags) => {
+  for (const flag of flags) {
+    const idx = argv.indexOf(flag);
+    if (idx !== -1 && idx + 1 < argv.length) {
+      return argv[idx + 1];
+    }
+  }
+  return undefined;
+};
+
+const kGlobalValueFlags = new Set(["--root-dir", "--port"]);
+const splitGlobalAndCommandArgs = (argv) => {
+  const globalArgs = [];
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (!token.startsWith("-")) break;
+    globalArgs.push(token);
+    if (kGlobalValueFlags.has(token) && index + 1 < argv.length) {
+      globalArgs.push(argv[index + 1]);
+      index += 2;
+      continue;
+    }
+    index += 1;
+  }
+  return {
+    globalArgs,
+    commandArgs: argv.slice(index),
+  };
+};
+
+const { globalArgs, commandArgs } = splitGlobalAndCommandArgs(args);
+const command = commandArgs[0];
+const commandScope = commandArgs[1];
+const commandAction = commandArgs[2];
 
-if (args.includes("--version") || args.includes("-v") || command === "version") {
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"),
+);
+
+if (
+  args.includes("--version") ||
+  args.includes("-v") ||
+  command === "version"
+) {
   console.log(pkg.version);
   process.exit(0);
 }
@@ -28,33 +70,55 @@ Usage: alphaclaw <command> [options]
 
 Commands:
   start     Start the AlphaClaw server (Setup UI + gateway manager)
+  git-sync  Commit and push /data/.openclaw safely using GITHUB_TOKEN
+  telegram topic add  Add/update Telegram topic mapping by thread ID
   version   Print version
 
-Options:
-  --root-dir <path>   Persistent data directory (default: ~/.alphaclaw)
-  --port <number>     Server port (default: 3000)
-  --version, -v       Print version
-  --help              Show this help message
+Global options:
+--version, -v       Print version
+--help              Show this help message
+
+start options:
+--root-dir <path>   Persistent data directory (default: ~/.alphaclaw)
+--port <number>     Server port (default: 3000)
+
+git-sync options:
+  --message, -m <text> Commit message
+
+telegram topic add options:
+  --thread <id>       Telegram thread ID
+  --name <text>       Topic name
+  --system <text>     Optional system instructions
+  --group <id>        Optional group ID override (auto-resolves when one group exists)
+
+Examples:
+  alphaclaw git-sync --message "sync workspace"
+  alphaclaw telegram topic add --thread 12 --name "Testing"
+  alphaclaw telegram topic add --thread 12 --name "Testing" --system "Handle QA requests"
 `);
   process.exit(0);
 }
 
-const flagValue = (flag) => {
-  const idx = args.indexOf(flag);
-  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
-};
+const quoteArg = (value) => `'${String(value || "").replace(/'/g, "'\"'\"'")}'`;
+const resolveGithubRepoPath = (value) =>
+  String(value || "")
+    .trim()
+    .replace(/^git@github\.com:/, "")
+    .replace(/^https:\/\/github\.com\//, "")
+    .replace(/\.git$/, "");
 
 // ---------------------------------------------------------------------------
 // 1. Resolve root directory (before requiring any lib/ modules)
 // ---------------------------------------------------------------------------
 
-const rootDir = flagValue("--root-dir")
-  || process.env.ALPHACLAW_ROOT_DIR
-  || path.join(os.homedir(), ".alphaclaw");
+const rootDir =
+  flagValue(globalArgs, "--root-dir") ||
+  process.env.ALPHACLAW_ROOT_DIR ||
+  path.join(os.homedir(), ".alphaclaw");
 
 process.env.ALPHACLAW_ROOT_DIR = rootDir;
 
-const portFlag = flagValue("--port");
+const portFlag = flagValue(globalArgs, "--port");
 if (portFlag) {
   process.env.PORT = portFlag;
 }
@@ -73,16 +137,24 @@ console.log(`[alphaclaw] Root directory: ${rootDir}`);
 // from the fresh container using the persistent volume marker.
 const pendingUpdateMarker = path.join(rootDir, ".alphaclaw-update-pending");
 if (fs.existsSync(pendingUpdateMarker)) {
-  console.log("[alphaclaw] Pending update detected, installing @chrysb/alphaclaw@latest...");
+  console.log(
+    "[alphaclaw] Pending update detected, installing @chrysb/alphaclaw@latest...",
+  );
   const alphaPkgRoot = path.resolve(__dirname, "..");
-  const nmIndex = alphaPkgRoot.lastIndexOf(`${path.sep}node_modules${path.sep}`);
-  const installDir = nmIndex >= 0 ? alphaPkgRoot.slice(0, nmIndex) : alphaPkgRoot;
+  const nmIndex = alphaPkgRoot.lastIndexOf(
+    `${path.sep}node_modules${path.sep}`,
+  );
+  const installDir =
+    nmIndex >= 0 ? alphaPkgRoot.slice(0, nmIndex) : alphaPkgRoot;
   try {
-    execSync("npm install @chrysb/alphaclaw@latest --omit=dev --prefer-online", {
-      cwd: installDir,
-      stdio: "inherit",
-      timeout: 180000,
-    });
+    execSync(
+      "npm install @chrysb/alphaclaw@latest --omit=dev --prefer-online",
+      {
+        cwd: installDir,
+        stdio: "inherit",
+        timeout: 180000,
+      },
+    );
     fs.unlinkSync(pendingUpdateMarker);
     console.log("[alphaclaw] Update applied successfully");
   } catch (e) {
@@ -154,6 +226,227 @@ if (fs.existsSync(envFilePath)) {
   console.log("[alphaclaw] Loaded .env");
 }
 
+const runGitSync = () => {
+  const githubToken = String(process.env.GITHUB_TOKEN || "").trim();
+  const githubRepo = resolveGithubRepoPath(
+    process.env.GITHUB_WORKSPACE_REPO || "",
+  );
+  const commitMessage = String(
+    flagValue(commandArgs, "--message", "-m") || "",
+  ).trim();
+  if (!commitMessage) {
+    console.error("[alphaclaw] Missing --message for git-sync");
+    return 1;
+  }
+  if (!githubToken) {
+    console.error("[alphaclaw] Missing GITHUB_TOKEN for git-sync");
+    return 1;
+  }
+  if (!githubRepo) {
+    console.error("[alphaclaw] Missing GITHUB_WORKSPACE_REPO for git-sync");
+    return 1;
+  }
+  if (!fs.existsSync(path.join(openclawDir, ".git"))) {
+    console.error("[alphaclaw] No git repository at /data/.openclaw");
+    return 1;
+  }
+
+  const originUrl = `https://github.com/${githubRepo}.git`;
+  let branch = "main";
+  try {
+    branch =
+      String(
+        execSync("git symbolic-ref --short HEAD", {
+          cwd: openclawDir,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }),
+      ).trim() || "main";
+  } catch {}
+  const askPassPath = path.join(
+    os.tmpdir(),
+    `alphaclaw-git-askpass-${process.pid}.sh`,
+  );
+  const runGit = (gitCommand, { withAuth = false } = {}) => {
+    const cmd = withAuth
+      ? `GIT_TERMINAL_PROMPT=0 GIT_ASKPASS=${quoteArg(askPassPath)} git ${gitCommand}`
+      : `git ${gitCommand}`;
+    return execSync(cmd, {
+      cwd: openclawDir,
+      stdio: "pipe",
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GITHUB_TOKEN: githubToken,
+      },
+    });
+  };
+
+  try {
+    fs.writeFileSync(
+      askPassPath,
+      [
+        "#!/usr/bin/env sh",
+        'case "$1" in',
+        '  *Username*) echo "x-access-token" ;;',
+        '  *Password*) echo "${GITHUB_TOKEN:-}" ;;',
+        '  *) echo "" ;;',
+        "esac",
+        "",
+      ].join("\n"),
+      { mode: 0o700 },
+    );
+
+    runGit(`remote set-url origin ${quoteArg(originUrl)}`);
+    runGit(`config user.name ${quoteArg("AlphaClaw Agent")}`);
+    runGit(`config user.email ${quoteArg("agent@alphaclaw.md")}`);
+    try {
+      runGit(`ls-remote --exit-code --heads origin ${quoteArg(branch)}`, {
+        withAuth: true,
+      });
+      runGit(`pull --rebase --autostash origin ${quoteArg(branch)}`, {
+        withAuth: true,
+      });
+    } catch {
+      console.log(
+        `[alphaclaw] Remote branch "${branch}" not found, skipping pull`,
+      );
+    }
+    runGit("add -A");
+    try {
+      runGit("diff --cached --quiet");
+      console.log("[alphaclaw] No changes to commit");
+      return 0;
+    } catch {}
+    runGit(`commit -m ${quoteArg(commitMessage)}`);
+    runGit(`push origin ${quoteArg(branch)}`, { withAuth: true });
+    const hash = String(runGit("rev-parse --short HEAD")).trim();
+    console.log(`[alphaclaw] Git sync complete (${hash})`);
+    console.log(
+      `[alphaclaw] Commit URL: https://github.com/${githubRepo}/commit/${hash}`,
+    );
+    return 0;
+  } catch (e) {
+    const details = String(e.stderr || e.stdout || e.message || "").trim();
+    console.error(`[alphaclaw] git-sync failed: ${details.slice(0, 400)}`);
+    return 1;
+  } finally {
+    try {
+      fs.rmSync(askPassPath, { force: true });
+    } catch {}
+  }
+};
+
+if (command === "git-sync") {
+  process.exit(runGitSync());
+}
+
+const runTelegramTopicAdd = () => {
+  const topicName = String(flagValue(commandArgs, "--name") || "").trim();
+  const threadId = String(flagValue(commandArgs, "--thread") || "").trim();
+  const systemInstructions = String(
+    flagValue(commandArgs, "--system") || "",
+  ).trim();
+  const requestedGroupId = String(
+    flagValue(commandArgs, "--group") || "",
+  ).trim();
+  if (!threadId) {
+    console.error("[alphaclaw] Missing --thread for telegram topic add");
+    return 1;
+  }
+  if (!topicName) {
+    console.error("[alphaclaw] Missing --name for telegram topic add");
+    return 1;
+  }
+
+  const configPath = path.join(openclawDir, "openclaw.json");
+  if (!fs.existsSync(configPath)) {
+    console.error("[alphaclaw] Missing openclaw.json. Run setup first.");
+    return 1;
+  }
+
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const configuredGroups = Object.keys(cfg.channels?.telegram?.groups || {});
+    let groupId = requestedGroupId;
+    if (!groupId) {
+      if (configuredGroups.length === 1) {
+        [groupId] = configuredGroups;
+      } else if (configuredGroups.length === 0) {
+        console.error(
+          "[alphaclaw] No Telegram group configured. Configure Telegram workspace first.",
+        );
+        return 1;
+      } else {
+        console.error(
+          "[alphaclaw] Multiple Telegram groups detected. Provide --group <groupId>.",
+        );
+        return 1;
+      }
+    }
+
+    const topicRegistry = require("../lib/server/topic-registry");
+    const {
+      syncConfigForTelegram,
+    } = require("../lib/server/telegram-workspace");
+    const {
+      syncBootstrapPromptFiles,
+    } = require("../lib/server/onboarding/workspace");
+    topicRegistry.updateTopic(groupId, threadId, {
+      name: topicName,
+      ...(systemInstructions ? { systemInstructions } : {}),
+    });
+
+    const requireMention =
+      !!cfg.channels?.telegram?.groups?.[groupId]?.requireMention;
+    const syncResult = syncConfigForTelegram({
+      fs,
+      openclawDir,
+      topicRegistry,
+      groupId,
+      requireMention,
+      resolvedUserId: "",
+    });
+    syncBootstrapPromptFiles({
+      fs,
+      workspaceDir: path.join(openclawDir, "workspace"),
+    });
+
+    console.log(
+      `[alphaclaw] Topic mapped: group=${groupId} thread=${threadId} name=${topicName}`,
+    );
+    console.log(
+      `[alphaclaw] Concurrency updated: agent=${syncResult.maxConcurrent} subagents=${syncResult.subagentMaxConcurrent} topics=${syncResult.totalTopics}`,
+    );
+    return 0;
+  } catch (e) {
+    console.error(`[alphaclaw] telegram topic add failed: ${e.message}`);
+    return 1;
+  }
+};
+
+if (
+  command === "telegram" &&
+  commandScope === "topic" &&
+  commandAction === "add"
+) {
+  process.exit(runTelegramTopicAdd());
+}
+
+const kSetupPassword = String(process.env.SETUP_PASSWORD || "").trim();
+if (!kSetupPassword) {
+  console.error(
+    [
+      "[alphaclaw] Fatal config error: SETUP_PASSWORD is missing or empty.",
+      "[alphaclaw] Set SETUP_PASSWORD in your deployment environment variables and restart.",
+      "[alphaclaw] Examples:",
+      "[alphaclaw] - Render: Dashboard -> Environment -> Add SETUP_PASSWORD",
+      "[alphaclaw] - Railway: Project -> Variables -> Add SETUP_PASSWORD",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
 // ---------------------------------------------------------------------------
 // 7. Set OPENCLAW_HOME globally so all child processes inherit it
 // ---------------------------------------------------------------------------
@@ -184,7 +477,10 @@ if (!gogInstalled) {
     const arch = os.arch() === "arm64" ? "arm64" : "amd64";
     const tarball = `gogcli_${gogVersion}_${platform}_${arch}.tar.gz`;
     const url = `https://github.com/steipete/gogcli/releases/download/v${gogVersion}/${tarball}`;
-    execSync(`curl -fsSL "${url}" -o /tmp/gog.tar.gz && tar -xzf /tmp/gog.tar.gz -C /tmp/ && mv /tmp/gog /usr/local/bin/gog && chmod +x /usr/local/bin/gog && rm -f /tmp/gog.tar.gz`, { stdio: "inherit" });
+    execSync(
+      `curl -fsSL "${url}" -o /tmp/gog.tar.gz && tar -xzf /tmp/gog.tar.gz -C /tmp/ && mv /tmp/gog /usr/local/bin/gog && chmod +x /usr/local/bin/gog && rm -f /tmp/gog.tar.gz`,
+      { stdio: "inherit" },
+    );
     console.log("[alphaclaw] gog CLI installed");
   } catch (e) {
     console.log(`[alphaclaw] gog install skipped: ${e.message}`);
@@ -195,7 +491,8 @@ if (!gogInstalled) {
 // 7. Configure gog keyring (file backend for headless environments)
 // ---------------------------------------------------------------------------
 
-process.env.GOG_KEYRING_PASSWORD = process.env.GOG_KEYRING_PASSWORD || "alphaclaw";
+process.env.GOG_KEYRING_PASSWORD =
+  process.env.GOG_KEYRING_PASSWORD || "alphaclaw";
 const gogConfigFile = path.join(openclawDir, "gogcli", "config.json");
 
 if (!fs.existsSync(gogConfigFile)) {
@@ -211,6 +508,31 @@ if (!fs.existsSync(gogConfigFile)) {
 // ---------------------------------------------------------------------------
 
 const hourlyGitSyncPath = path.join(openclawDir, "hourly-git-sync.sh");
+const packagedHourlyGitSyncPath = path.join(setupDir, "hourly-git-sync.sh");
+
+try {
+  if (fs.existsSync(packagedHourlyGitSyncPath)) {
+    const packagedSyncScript = fs.readFileSync(
+      packagedHourlyGitSyncPath,
+      "utf8",
+    );
+    const installedSyncScript = fs.existsSync(hourlyGitSyncPath)
+      ? fs.readFileSync(hourlyGitSyncPath, "utf8")
+      : "";
+    const shouldInstallSyncScript =
+      !installedSyncScript ||
+      !installedSyncScript.includes("GIT_ASKPASS") ||
+      !installedSyncScript.includes("GITHUB_TOKEN");
+    if (shouldInstallSyncScript && packagedSyncScript.trim()) {
+      fs.writeFileSync(hourlyGitSyncPath, packagedSyncScript, { mode: 0o755 });
+      console.log("[alphaclaw] Refreshed hourly git sync script");
+    }
+  }
+} catch (e) {
+  console.log(
+    `[alphaclaw] Hourly git sync script refresh skipped: ${e.message}`,
+  );
+}
 
 if (fs.existsSync(hourlyGitSyncPath)) {
   try {
@@ -238,7 +560,9 @@ if (fs.existsSync(hourlyGitSyncPath)) {
       fs.writeFileSync(cronFilePath, cronContent, { mode: 0o644 });
       console.log("[alphaclaw] System cron entry installed");
     } else {
-      try { fs.unlinkSync(cronFilePath); } catch {}
+      try {
+        fs.unlinkSync(cronFilePath);
+      } catch {}
       console.log("[alphaclaw] System cron entry disabled");
     }
   } catch (e) {
@@ -271,13 +595,18 @@ if (process.env.GOG_CLIENT_CREDENTIALS_JSON && process.env.GOG_REFRESH_TOKEN) {
     fs.writeFileSync(tmpCreds, process.env.GOG_CLIENT_CREDENTIALS_JSON);
     execSync(`gog auth credentials set "${tmpCreds}"`, { stdio: "ignore" });
     fs.unlinkSync(tmpCreds);
-    fs.writeFileSync(tmpToken, JSON.stringify({
-      email: process.env.GOG_ACCOUNT || "",
-      refresh_token: process.env.GOG_REFRESH_TOKEN,
-    }));
+    fs.writeFileSync(
+      tmpToken,
+      JSON.stringify({
+        email: process.env.GOG_ACCOUNT || "",
+        refresh_token: process.env.GOG_REFRESH_TOKEN,
+      }),
+    );
     execSync(`gog auth tokens import "${tmpToken}"`, { stdio: "ignore" });
     fs.unlinkSync(tmpToken);
-    console.log(`[alphaclaw] gog CLI configured for ${process.env.GOG_ACCOUNT || "account"}`);
+    console.log(
+      `[alphaclaw] gog CLI configured for ${process.env.GOG_ACCOUNT || "account"}`,
+    );
   } catch (e) {
     console.log(`[alphaclaw] gog credentials setup skipped: ${e.message}`);
   }
@@ -294,17 +623,42 @@ const configPath = path.join(openclawDir, "openclaw.json");
 if (fs.existsSync(configPath)) {
   console.log("[alphaclaw] Config exists, reconciling channels...");
 
-  const githubToken = process.env.GITHUB_TOKEN;
   const githubRepo = process.env.GITHUB_WORKSPACE_REPO;
-  if (githubToken && githubRepo && fs.existsSync(path.join(openclawDir, ".git"))) {
-    const repoUrl = githubRepo
-      .replace(/^git@github\.com:/, "")
-      .replace(/^https:\/\/github\.com\//, "")
-      .replace(/\.git$/, "");
-    const remoteUrl = `https://${githubToken}@github.com/${repoUrl}.git`;
+  if (fs.existsSync(path.join(openclawDir, ".git"))) {
+    if (githubRepo) {
+      const repoUrl = githubRepo
+        .replace(/^git@github\.com:/, "")
+        .replace(/^https:\/\/github\.com\//, "")
+        .replace(/\.git$/, "");
+      const remoteUrl = `https://github.com/${repoUrl}.git`;
+      try {
+        execSync(`git remote set-url origin "${remoteUrl}"`, {
+          cwd: openclawDir,
+          stdio: "ignore",
+        });
+        console.log("[alphaclaw] Repo ready");
+      } catch {}
+    }
+
+    // Migration path: scrub persisted PATs from existing GitHub origin URLs.
     try {
-      execSync(`git remote set-url origin "${remoteUrl}"`, { cwd: openclawDir, stdio: "ignore" });
-      console.log("[alphaclaw] Repo ready");
+      const existingOrigin = execSync("git remote get-url origin", {
+        cwd: openclawDir,
+        stdio: ["ignore", "pipe", "ignore"],
+        encoding: "utf8",
+      }).trim();
+      const match = existingOrigin.match(
+        /^https:\/\/[^/@]+@github\.com\/(.+)$/i,
+      );
+      if (match?.[1]) {
+        const cleanedPath = String(match[1]).replace(/\.git$/i, "");
+        const cleanedOrigin = `https://github.com/${cleanedPath}.git`;
+        execSync(`git remote set-url origin "${cleanedOrigin}"`, {
+          cwd: openclawDir,
+          stdio: "ignore",
+        });
+        console.log("[alphaclaw] Scrubbed tokenized GitHub remote URL");
+      }
     } catch {}
   }
 
@@ -341,19 +695,9 @@ if (fs.existsSync(configPath)) {
 
     if (changed) {
       let content = JSON.stringify(cfg, null, 2);
-      const replacements = [
-        [process.env.OPENCLAW_GATEWAY_TOKEN, "${OPENCLAW_GATEWAY_TOKEN}"],
-        [process.env.ANTHROPIC_API_KEY, "${ANTHROPIC_API_KEY}"],
-        [process.env.ANTHROPIC_TOKEN, "${ANTHROPIC_TOKEN}"],
-        [process.env.TELEGRAM_BOT_TOKEN, "${TELEGRAM_BOT_TOKEN}"],
-        [process.env.DISCORD_BOT_TOKEN, "${DISCORD_BOT_TOKEN}"],
-        [process.env.OPENAI_API_KEY, "${OPENAI_API_KEY}"],
-        [process.env.GEMINI_API_KEY, "${GEMINI_API_KEY}"],
-        [process.env.NOTION_API_KEY, "${NOTION_API_KEY}"],
-        [process.env.BRAVE_API_KEY, "${BRAVE_API_KEY}"],
-      ];
+      const replacements = buildSecretReplacements(process.env);
       for (const [secret, envRef] of replacements) {
-        if (secret && secret.length > 8) {
+        if (secret) {
           content = content.split(secret).join(envRef);
         }
       }
@@ -364,7 +708,9 @@ if (fs.existsSync(configPath)) {
     console.error(`[alphaclaw] Channel reconciliation error: ${e.message}`);
   }
 } else {
-  console.log("[alphaclaw] No config yet -- onboarding will run from the Setup UI");
+  console.log(
+    "[alphaclaw] No config yet -- onboarding will run from the Setup UI",
+  );
 }
 
 // ---------------------------------------------------------------------------

package/lib/public/js/app.js

@@ -28,12 +28,14 @@ import { Providers } from "./components/providers.js";
 import { Welcome } from "./components/welcome.js";
 import { Envars } from "./components/envars.js";
 import { ToastContainer, showToast } from "./components/toast.js";
+import { TelegramWorkspace } from "./components/telegram-workspace.js";
 import { ChevronDownIcon } from "./components/icons.js";
 const html = htm.bind(h);
 const kUiTabs = ["general", "providers", "envars"];
+const kSubScreens = ["telegram"];
 const kDefaultUiTab = "general";
 
-const GeneralTab = ({ onSwitchTab, isActive }) => {
+const GeneralTab = ({ onSwitchTab, onNavigate, isActive }) => {
   const [googleKey, setGoogleKey] = useState(0);
   const [dashboardLoading, setDashboardLoading] = useState(false);
 
@@ -156,7 +158,7 @@ const GeneralTab = ({ onSwitchTab, isActive }) => {
   return html`
     <div class="space-y-4">
       <${Gateway} status=${gatewayStatus} openclawVersion=${openclawVersion} />
-      <${Channels} channels=${channels} onSwitchTab=${onSwitchTab} />
+      <${Channels} channels=${channels} onSwitchTab=${onSwitchTab} onNavigate=${onNavigate} />
       <${Pairings}
         pending=${pending}
         channels=${channels}
@@ -282,8 +284,13 @@ function App() {
   const [onboarded, setOnboarded] = useState(null);
   const [tab, setTab] = useState(() => {
     const hash = window.location.hash.replace("#", "");
+    if (kSubScreens.includes(hash)) return kDefaultUiTab;
     return kUiTabs.includes(hash) ? hash : kDefaultUiTab;
   });
+  const [subScreen, setSubScreen] = useState(() => {
+    const hash = window.location.hash.replace("#", "");
+    return kSubScreens.includes(hash) ? hash : null;
+  });
   const [acVersion, setAcVersion] = useState(null);
   const [acLatest, setAcLatest] = useState(null);
   const [acHasUpdate, setAcHasUpdate] = useState(false);
@@ -316,8 +323,8 @@ function App() {
   }, []);
 
   useEffect(() => {
-    history.replaceState(null, "", `#${tab}`);
-  }, [tab]);
+    history.replaceState(null, "", `#${subScreen || tab}`);
+  }, [tab, subScreen]);
 
   useEffect(() => {
     if (!onboarded) return;
@@ -401,6 +408,9 @@ function App() {
     `;
   }
 
+  const navigateToSubScreen = (screen) => setSubScreen(screen);
+  const exitSubScreen = () => setSubScreen(null);
+
   const kNavItems = [
     { id: "general", label: "General" },
     { id: "providers", label: "Providers" },
@@ -447,8 +457,8 @@ function App() {
           ${kNavItems.map(
             (item) => html`
               <a
-                class=${tab === item.id ? "active" : ""}
-                onclick=${() => setTab(item.id)}
+                class=${tab === item.id && !subScreen ? "active" : ""}
+                onclick=${() => { setSubScreen(null); setTab(item.id); }}
               >
                 ${item.label}
               </a>
@@ -471,19 +481,28 @@ function App() {
       </div>
 
       <div class="app-content">
-        <div class="max-w-2xl w-full mx-auto space-y-4">
-          <div style=${{ display: tab === "general" ? "" : "none" }}>
-            <${GeneralTab}
-              onSwitchTab=${setTab}
-              isActive=${tab === "general"}
-            />
-          </div>
-          <div style=${{ display: tab === "providers" ? "" : "none" }}>
-            <${Providers} />
-          </div>
-          <div style=${{ display: tab === "envars" ? "" : "none" }}>
-            <${Envars} />
-          </div>
+        <div class="max-w-2xl w-full mx-auto">
+          ${subScreen === "telegram"
+            ? html`
+              <div class="pt-4">
+                <${TelegramWorkspace} onBack=${exitSubScreen} />
+              </div>
+            `
+            : html`
+              <div class="pt-4" style=${{ display: tab === "general" ? "" : "none" }}>
+                <${GeneralTab}
+                  onSwitchTab=${setTab}
+                  onNavigate=${navigateToSubScreen}
+                  isActive=${tab === "general" && !subScreen}
+                />
+              </div>
+              <div class="pt-4" style=${{ display: tab === "providers" ? "" : "none" }}>
+                <${Providers} />
+              </div>
+              <div class="pt-4" style=${{ display: tab === "envars" ? "" : "none" }}>
+                <${Envars} />
+              </div>
+            `}
         </div>
       </div>