appback-remoteagent 0.18.0 → 0.20.0

package/README.md

@@ -318,6 +318,34 @@ remoteagent-start
 
 `remoteagent-install` seeds provider install/login hook paths into `~/.remoteagent/.env` automatically, so `/install codex` and `/install claude` work on a fresh machine without manual hook wiring.
 
+Register the first Telegram bot without editing `.env` manually:
+
+```bash
+remoteagent bot add
+remoteagent-start
+```
+
+The command validates the BotFather token, stores the bot configuration, and configures the numeric Telegram owner user ID. Tokens are entered through a hidden prompt by default.
+
+To move installation-wide `/secret` values to another PC, export and import a password-encrypted bundle:
+
+```bash
+# Old PC
+remoteagent secret export ~/remoteagent-secrets.ra-secrets
+
+# New PC
+remoteagent secret import ~/remoteagent-secrets.ra-secrets
+```
+
+See [CLI bootstrap and secret migration](./docs/CLI_BOOTSTRAP_AND_SECRET_MIGRATION.md) for the complete interactive and automation-safe commands.
+
+Selected Secret keys can also be returned to the current private Telegram chat as a compressed, encrypted bundle without exposing values to the provider:
+
+```text
+/secret set REMOTEAGENT_TRANSFER_PASSPHRASE a-long-private-passphrase
+/secret export REMOTEAGENT_TRANSFER_PASSPHRASE KEY_ONE KEY_TWO
+```
+
 For one-line installs on a fresh machine:
 
 ```bash

package/bin/remoteagent.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import "../dist/index.js";
+import "../dist/cli.js";

package/dist/bot.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
@@ -10,6 +11,7 @@ import { ProviderSetupService } from "./services/provider-setup-service.js";
 import { RemoteShellService } from "./services/remote-shell-service.js";
 import { AgentMemoryService } from "./services/agent-memory-service.js";
 import { WorkspaceCleanupService } from "./services/workspace-cleanup-service.js";
+import { exportSecrets } from "./services/secret-transfer-service.js";
 import { deleteTelegramCommandMenu, setTelegramCommandMenu } from "./telegram-command-menu.js";
 const execFileAsync = promisify(execFile);
 const HELP_TEXT = [
@@ -32,7 +34,7 @@ const HELP_TEXT = [
     "/state [clear|note <text>]",
     "/artifacts list|cleanup <days>",
     "/cleanup",
-    "/secret set|list|remove",
+    "/secret set|list|remove|export",
     "/docs pin|find|list|remove|reinforce",
     "/macro set|list|remove|<alias|number>",
     "/매크로 set|list|remove|<alias|number>",
@@ -782,9 +784,46 @@ ${bridge.formatStatus(mapping)}`);
                 return;
             }
             await memoryService.setSecret(key, rest.trim());
+            if (ctx.chat && ctx.message?.message_id) {
+                await deleteTelegramMessage(token, ctx.chat.id, ctx.message.message_id).catch((error) => {
+                    console.warn(`[secret] failed to delete source message for ${key}: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            }
             await reply(ctx, `Stored secret key ${key}. Value is hidden from agents and chat output.`);
             return;
         }
+        if (action === "export") {
+            if (!key || !ctx.chat) {
+                await reply(ctx, formatSecretHelp(), { parse_mode: "Markdown" });
+                return;
+            }
+            const passphrase = await memoryService.getSecret(key);
+            if (!passphrase) {
+                await reply(ctx, `Secret key was not found: ${key}`);
+                return;
+            }
+            const selectedKeys = rest
+                ?.split(/\s+/)
+                .map((value) => value.trim().toUpperCase())
+                .filter(Boolean);
+            const mapping = await bridge.status(getBotId(), String(ctx.chat.id)).catch(() => undefined);
+            const exportDir = await fs.mkdtemp(path.join(os.tmpdir(), "remoteagent-secret-export-"));
+            const exportPath = path.join(exportDir, `remoteagent-secrets-${mapping?.session.publicId ?? "install"}-${new Date().toISOString().slice(0, 10)}.ra-secrets`);
+            try {
+                const result = await exportSecrets(config.dataDir, exportPath, passphrase, {
+                    includeKeys: selectedKeys,
+                    excludeKeys: [key],
+                });
+                await sendTelegramDocument(token, ctx.chat.id, {
+                    path: result.outputPath,
+                    caption: `Encrypted RemoteAgent Secret bundle (${result.count} key(s)). Secret values are not shown.`,
+                });
+            }
+            finally {
+                await fs.rm(exportDir, { recursive: true, force: true }).catch(() => undefined);
+            }
+            return;
+        }
         if (action === "remove") {
             if (!key) {
                 await reply(ctx, formatSecretHelp(), { parse_mode: "Markdown" });
@@ -2411,12 +2450,15 @@ function formatSecretHelp() {
         "/secret set KEY value",
         "/secret list",
         "/secret remove KEY",
+        "/secret export PASSPHRASE_KEY [KEY ...]",
         "```",
         "",
         "Example:",
         "```text",
         "/secret set GIFTISHOW_AUTH_KEY REAL...",
         "/secret set GIFTISHOW_TOKEN_KEY xNC...",
+        "/secret set REMOTEAGENT_TRANSFER_PASSPHRASE a-long-private-passphrase",
+        "/secret export REMOTEAGENT_TRANSFER_PASSPHRASE GIFTISHOW_AUTH_KEY GIFTISHOW_TOKEN_KEY",
         "```",
         "",
         "Then tell the agent:",
@@ -3009,6 +3051,25 @@ async function sendTelegramDocument(botToken, chatId, document) {
     }
     return payload.result;
 }
+async function deleteTelegramMessage(botToken, chatId, messageId) {
+    const { stdout, stderr } = await execFileAsync("curl", [
+        "-sS",
+        "--max-time",
+        "20",
+        "-d",
+        `chat_id=${chatId}`,
+        "-d",
+        `message_id=${messageId}`,
+        `https://api.telegram.org/bot${botToken}/deleteMessage`,
+    ]);
+    if (stderr?.trim()) {
+        console.error(`curl stderr for deleteMessage: ${stderr.trim()}`);
+    }
+    const payload = JSON.parse(stdout);
+    if (!payload.ok) {
+        throw new Error(payload.description || "Telegram API deleteMessage failed.");
+    }
+}
 async function sendTelegramMessage(botToken, chatId, text, extra) {
     const startedAt = Date.now();
     try {

package/dist/cli.js

@@ -0,0 +1,208 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline/promises";
+import { registerTelegramBot, readConfiguredOwnerId } from "./services/cli-config-service.js";
+import { exportSecrets, importSecrets } from "./services/secret-transfer-service.js";
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        await import("./index.js");
+        return;
+    }
+    if (["help", "--help", "-h"].includes(args[0])) {
+        printHelp();
+        return;
+    }
+    const dataDir = path.resolve(takeOption(args, "--data-dir") || process.env.DATA_DIR?.trim() || path.join(os.homedir(), ".remoteagent"));
+    const [group, action] = args;
+    if (group === "bot" && action === "add") {
+        await addBot(dataDir, args.slice(2));
+        return;
+    }
+    if (group === "secret" && action === "export") {
+        await exportSecretCommand(dataDir, args.slice(2));
+        return;
+    }
+    if (group === "secret" && action === "import") {
+        await importSecretCommand(dataDir, args.slice(2));
+        return;
+    }
+    throw new Error(`Unknown command: ${args.join(" ")}\n\nRun 'remoteagent --help' for usage.`);
+}
+async function addBot(dataDir, args) {
+    const ownerOption = takeOption(args, "--owner");
+    const tokenFile = takeOption(args, "--token-file");
+    if (args.some((arg) => arg.startsWith("--"))) {
+        throw new Error(`Unknown bot option: ${args.find((arg) => arg.startsWith("--"))}`);
+    }
+    if (tokenFile && args[0]) {
+        throw new Error("Provide the bot token either as an argument or with --token-file, not both.");
+    }
+    const token = tokenFile
+        ? await readSingleLineFile(tokenFile)
+        : args.shift() || await promptHidden("Telegram bot token: ");
+    if (args.length > 0) {
+        throw new Error(`Unexpected bot argument: ${args[0]}`);
+    }
+    const configuredOwner = await readConfiguredOwnerId(dataDir);
+    const ownerId = ownerOption || configuredOwner || await promptVisible("Telegram owner user ID: ");
+    const result = await registerTelegramBot({ dataDir, token, ownerId });
+    console.log([
+        `${result.added ? "Registered" : "Updated"} @${result.identity.username} (${result.identity.id}).`,
+        `Configured bots: ${result.botCount}`,
+        `Configuration: ${result.envPath}`,
+        "Start or restart RemoteAgent to apply it:",
+        "  remoteagent-start",
+        "  # systemd runtime: sudo systemctl restart remoteagent",
+    ].join("\n"));
+}
+async function exportSecretCommand(dataDir, args) {
+    const passphraseFile = takeOption(args, "--passphrase-file");
+    if (args.some((arg) => arg.startsWith("--"))) {
+        throw new Error(`Unknown secret export option: ${args.find((arg) => arg.startsWith("--"))}`);
+    }
+    const outputPath = args.shift() || path.resolve(`remoteagent-secrets-${formatDate(new Date())}.ra-secrets`);
+    if (args.length > 0) {
+        throw new Error(`Unexpected secret export argument: ${args[0]}`);
+    }
+    const passphrase = passphraseFile
+        ? await readSingleLineFile(passphraseFile)
+        : await promptConfirmedPassphrase();
+    const result = await exportSecrets(dataDir, outputPath, passphrase);
+    console.log([
+        `Exported ${result.count} secret(s) to ${result.outputPath}.`,
+        "The bundle is encrypted. Transfer it together with neither the passphrase nor the source secret store.",
+    ].join("\n"));
+}
+async function importSecretCommand(dataDir, args) {
+    const passphraseFile = takeOption(args, "--passphrase-file");
+    const replace = takeFlag(args, "--replace");
+    if (args.some((arg) => arg.startsWith("--"))) {
+        throw new Error(`Unknown secret import option: ${args.find((arg) => arg.startsWith("--"))}`);
+    }
+    const inputPath = args.shift();
+    if (!inputPath) {
+        throw new Error("Usage: remoteagent secret import <file> [--replace]");
+    }
+    if (args.length > 0) {
+        throw new Error(`Unexpected secret import argument: ${args[0]}`);
+    }
+    const passphrase = passphraseFile
+        ? await readSingleLineFile(passphraseFile)
+        : await promptHidden("Secret bundle passphrase: ");
+    const result = await importSecrets(dataDir, inputPath, passphrase, replace);
+    console.log([
+        `Imported ${result.imported} secret(s); overwritten=${result.overwritten}; total=${result.total}.`,
+        result.backupPath ? `Previous secret store backup: ${result.backupPath}` : "No previous secret store required a backup.",
+        "Secret values were not printed.",
+    ].join("\n"));
+}
+function takeOption(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0) {
+        return undefined;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${name} requires a value.`);
+    }
+    args.splice(index, 2);
+    return value;
+}
+function takeFlag(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0) {
+        return false;
+    }
+    args.splice(index, 1);
+    return true;
+}
+async function promptVisible(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error(`${question.trim()} is required as a command option in non-interactive mode.`);
+    }
+    const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await terminal.question(question)).trim();
+    }
+    finally {
+        terminal.close();
+    }
+}
+async function promptHidden(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || !process.stdin.setRawMode) {
+        throw new Error("Interactive hidden input requires a TTY. Use the corresponding --*-file option instead.");
+    }
+    process.stdout.write(question);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    return new Promise((resolve, reject) => {
+        let value = "";
+        const cleanup = () => {
+            process.stdin.off("data", onData);
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === "\u0003") {
+                    cleanup();
+                    reject(new Error("Cancelled."));
+                    return;
+                }
+                if (char === "\r" || char === "\n") {
+                    cleanup();
+                    resolve(value);
+                    return;
+                }
+                if (char === "\u007f" || char === "\b") {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += char;
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
+async function promptConfirmedPassphrase() {
+    const first = await promptHidden("Secret bundle passphrase: ");
+    const second = await promptHidden("Confirm passphrase: ");
+    if (first !== second) {
+        throw new Error("Passphrases did not match.");
+    }
+    return first;
+}
+async function readSingleLineFile(filePath) {
+    const value = await fs.readFile(path.resolve(filePath), "utf8");
+    return value.replace(/[\r\n]+$/, "");
+}
+function formatDate(date) {
+    return date.toISOString().slice(0, 10).replace(/-/g, "");
+}
+function printHelp() {
+    console.log(`RemoteAgent CLI
+
+Usage:
+  remoteagent                         Start the foreground runtime
+  remoteagent bot add [token] [--owner <telegram-user-id>]
+  remoteagent bot add --token-file <file> --owner <telegram-user-id>
+  remoteagent secret export [file] [--passphrase-file <file>]
+  remoteagent secret import <file> [--replace] [--passphrase-file <file>]
+
+Global option:
+  --data-dir <path>                   Default: ~/.remoteagent
+
+Security:
+  Omit tokens and passphrases for hidden interactive prompts. File options are
+  intended for automation and keep sensitive values out of shell history.`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`RemoteAgent CLI error: ${message}`);
+    process.exitCode = 1;
+});

package/dist/services/cli-config-service.js

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function registerTelegramBot(options) {
+    const token = options.token.trim();
+    const ownerId = options.ownerId.trim();
+    assertBotToken(token);
+    assertOwnerId(ownerId);
+    const identity = options.identity ?? await fetchTelegramBotIdentity(token);
+    const envPath = path.join(options.dataDir, ".env");
+    const original = await fs.readFile(envPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
+    });
+    const values = parseEnv(original);
+    const configuredTokens = parseCsv(values.get("TELEGRAM_BOT_TOKENS") || values.get("TELEGRAM_BOT_TOKEN") || "");
+    const configuredUsernames = parseCsv(values.get("TELEGRAM_BOT_USERNAMES") || "");
+    const validIndexes = configuredTokens
+        .map((configuredToken, index) => isBotToken(configuredToken) ? index : -1)
+        .filter((index) => index >= 0);
+    const tokens = validIndexes.map((index) => configuredTokens[index]);
+    const usernames = validIndexes.map((index) => configuredUsernames[index] || "");
+    const existingIndex = tokens.indexOf(token);
+    const usernameIndex = usernames.findIndex((value) => value.toLowerCase() === identity.username.toLowerCase());
+    if (usernameIndex >= 0 && existingIndex < 0) {
+        throw new Error(`Telegram bot @${identity.username} is already configured with another token.`);
+    }
+    const added = existingIndex < 0;
+    if (added) {
+        tokens.push(token);
+        usernames.push(identity.username);
+    }
+    else {
+        while (usernames.length < tokens.length) {
+            usernames.push("");
+        }
+        usernames[existingIndex] = identity.username;
+    }
+    const next = upsertEnv(original, {
+        TELEGRAM_BOT_TOKEN: tokens[0],
+        TELEGRAM_BOT_TOKENS: tokens.join(","),
+        TELEGRAM_BOT_USERNAMES: usernames.join(","),
+        TELEGRAM_OWNER_ID: ownerId,
+    });
+    await atomicWrite(envPath, next, 0o600);
+    return {
+        identity,
+        envPath,
+        added,
+        botCount: tokens.length,
+    };
+}
+export async function readConfiguredOwnerId(dataDir) {
+    const envPath = path.join(dataDir, ".env");
+    const text = await fs.readFile(envPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
+    });
+    return parseEnv(text).get("TELEGRAM_OWNER_ID")?.trim() || undefined;
+}
+export async function fetchTelegramBotIdentity(token) {
+    assertBotToken(token);
+    let response;
+    try {
+        response = await fetch(`https://api.telegram.org/bot${token}/getMe`, {
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        throw new Error("Telegram getMe request failed. Check this machine's network and DNS, then retry.");
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error(`Telegram getMe returned an invalid response (HTTP ${response.status}).`);
+    }
+    if (!response.ok || !payload.ok || !payload.result?.id || !payload.result.username) {
+        throw new Error(payload.description || `Telegram rejected the supplied bot token (HTTP ${response.status}).`);
+    }
+    return {
+        id: payload.result.id,
+        username: payload.result.username,
+    };
+}
+function assertBotToken(token) {
+    if (!isBotToken(token)) {
+        throw new Error("Invalid Telegram bot token format.");
+    }
+}
+function isBotToken(token) {
+    return /^\d+:[A-Za-z0-9_-]{20,}$/.test(token);
+}
+function assertOwnerId(ownerId) {
+    if (!/^\d+$/.test(ownerId)) {
+        throw new Error("Telegram owner ID must contain digits only.");
+    }
+}
+function parseCsv(value) {
+    return value
+        .split(/[\r\n,]+/)
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parseEnv(text) {
+    const result = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^([A-Z0-9_]+)=(.*)$/.exec(line);
+        if (match) {
+            result.set(match[1], match[2]);
+        }
+    }
+    return result;
+}
+function upsertEnv(text, replacements) {
+    const remaining = new Map(Object.entries(replacements));
+    const lines = text.split(/\r?\n/);
+    const output = [];
+    for (const line of lines) {
+        const match = /^([A-Z0-9_]+)=/.exec(line);
+        const key = match?.[1];
+        if (key && remaining.has(key)) {
+            output.push(`${key}=${remaining.get(key)}`);
+            remaining.delete(key);
+        }
+        else if (line || output.length > 0) {
+            output.push(line);
+        }
+    }
+    while (output.at(-1) === "") {
+        output.pop();
+    }
+    for (const [key, value] of remaining) {
+        output.push(`${key}=${value}`);
+    }
+    return `${output.join("\n")}\n`;
+}
+async function atomicWrite(filePath, content, mode) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.writeFile(tempPath, content, { encoding: "utf8", mode });
+        await fs.chmod(tempPath, mode).catch(() => undefined);
+        await fs.rename(tempPath, filePath);
+        await fs.chmod(filePath, mode).catch(() => undefined);
+    }
+    finally {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+    }
+}

package/dist/services/secret-transfer-service.js

@@ -0,0 +1,237 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+const BUNDLE_FORMAT = "remoteagent-secret-bundle";
+const BUNDLE_VERSION = 1;
+const AAD = Buffer.from(`${BUNDLE_FORMAT}:v${BUNDLE_VERSION}`, "utf8");
+export async function exportSecrets(dataDir, outputPath, passphrase, options = {}) {
+    assertPassphrase(passphrase);
+    const secretsPath = path.join(dataDir, "managed", "secrets.json");
+    const storedSecrets = await readSecrets(secretsPath, false);
+    const secrets = selectSecrets(storedSecrets, options);
+    const payload = {
+        exportedAt: new Date().toISOString(),
+        secrets,
+    };
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = await deriveKey(passphrase, salt);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(AAD);
+    const compressedPayload = gzipSync(Buffer.from(JSON.stringify(payload), "utf8"));
+    const encrypted = Buffer.concat([
+        cipher.update(compressedPayload),
+        cipher.final(),
+    ]);
+    const bundle = {
+        format: BUNDLE_FORMAT,
+        version: BUNDLE_VERSION,
+        compression: "gzip",
+        kdf: {
+            name: "scrypt",
+            salt: salt.toString("base64"),
+        },
+        cipher: {
+            name: "aes-256-gcm",
+            iv: iv.toString("base64"),
+            tag: cipher.getAuthTag().toString("base64"),
+        },
+        data: encrypted.toString("base64"),
+    };
+    const resolvedOutputPath = path.resolve(outputPath);
+    await atomicWrite(resolvedOutputPath, `${JSON.stringify(bundle, null, 2)}\n`, 0o600);
+    return {
+        outputPath: resolvedOutputPath,
+        count: Object.keys(secrets).length,
+    };
+}
+function selectSecrets(secrets, options) {
+    const excluded = new Set((options.excludeKeys ?? []).map((key) => key.trim().toUpperCase()).filter(Boolean));
+    const requested = (options.includeKeys ?? []).map((key) => key.trim().toUpperCase()).filter(Boolean);
+    const selected = {};
+    if (requested.length > 0) {
+        const missing = requested.filter((key) => !secrets[key]);
+        if (missing.length > 0) {
+            throw new Error(`Secret key was not found: ${missing.join(", ")}`);
+        }
+        for (const key of requested) {
+            if (!excluded.has(key)) {
+                selected[key] = secrets[key];
+            }
+        }
+    }
+    else {
+        for (const [key, record] of Object.entries(secrets)) {
+            if (!excluded.has(key)) {
+                selected[key] = record;
+            }
+        }
+    }
+    if (Object.keys(selected).length === 0) {
+        throw new Error("No Secret values remain to export.");
+    }
+    return selected;
+}
+export async function importSecrets(dataDir, inputPath, passphrase, replace = false) {
+    assertPassphrase(passphrase);
+    const resolvedInputPath = path.resolve(inputPath);
+    const bundle = parseBundle(await fs.readFile(resolvedInputPath, "utf8"));
+    const salt = decodeBase64(bundle.kdf.salt, "salt");
+    const iv = decodeBase64(bundle.cipher.iv, "iv");
+    const tag = decodeBase64(bundle.cipher.tag, "authentication tag");
+    const encrypted = decodeBase64(bundle.data, "encrypted data");
+    const key = await deriveKey(passphrase, salt);
+    let plaintext;
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, iv);
+        decipher.setAAD(AAD);
+        decipher.setAuthTag(tag);
+        plaintext = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    }
+    catch {
+        throw new Error("Secret bundle could not be decrypted. Check the passphrase and file integrity.");
+    }
+    let decodedPayload = plaintext;
+    if (bundle.compression === "gzip") {
+        try {
+            decodedPayload = gunzipSync(plaintext);
+        }
+        catch {
+            throw new Error("Secret bundle compressed payload is invalid.");
+        }
+    }
+    const payload = parsePayload(decodedPayload.toString("utf8"));
+    const secretsPath = path.join(dataDir, "managed", "secrets.json");
+    const existing = await readSecrets(secretsPath, true);
+    const incomingKeys = Object.keys(payload.secrets);
+    const overwritten = incomingKeys.filter((keyName) => Boolean(existing[keyName])).length;
+    const merged = replace ? payload.secrets : { ...existing, ...payload.secrets };
+    let backupPath;
+    if (Object.keys(existing).length > 0) {
+        backupPath = `${secretsPath}.backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+        await fs.mkdir(path.dirname(backupPath), { recursive: true });
+        await fs.copyFile(secretsPath, backupPath);
+        await fs.chmod(backupPath, 0o600).catch(() => undefined);
+    }
+    await atomicWrite(secretsPath, `${JSON.stringify(merged, null, 2)}\n`, 0o600);
+    return {
+        imported: incomingKeys.length,
+        overwritten,
+        total: Object.keys(merged).length,
+        backupPath,
+    };
+}
+function parseBundle(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Secret bundle is not valid JSON.");
+    }
+    const bundle = value;
+    if (bundle.format !== BUNDLE_FORMAT
+        || bundle.version !== BUNDLE_VERSION
+        || (bundle.compression !== undefined && bundle.compression !== "gzip")
+        || bundle.kdf?.name !== "scrypt"
+        || bundle.cipher?.name !== "aes-256-gcm"
+        || typeof bundle.kdf.salt !== "string"
+        || typeof bundle.cipher.iv !== "string"
+        || typeof bundle.cipher.tag !== "string"
+        || typeof bundle.data !== "string") {
+        throw new Error("Unsupported or malformed RemoteAgent secret bundle.");
+    }
+    return bundle;
+}
+function parsePayload(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Decrypted secret payload is invalid.");
+    }
+    const payload = value;
+    if (!payload.secrets || typeof payload.secrets !== "object" || Array.isArray(payload.secrets)) {
+        throw new Error("Decrypted secret payload has no valid secret records.");
+    }
+    validateSecrets(payload.secrets);
+    return payload;
+}
+async function readSecrets(filePath, missingIsEmpty) {
+    let text;
+    try {
+        text = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            if (missingIsEmpty) {
+                return {};
+            }
+            throw new Error(`No RemoteAgent secrets were found at ${filePath}.`);
+        }
+        throw error;
+    }
+    let secrets;
+    try {
+        secrets = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`RemoteAgent secret store is invalid JSON: ${filePath}`);
+    }
+    if (!secrets || typeof secrets !== "object" || Array.isArray(secrets)) {
+        throw new Error(`RemoteAgent secret store is malformed: ${filePath}`);
+    }
+    validateSecrets(secrets);
+    return secrets;
+}
+function validateSecrets(secrets) {
+    for (const [key, record] of Object.entries(secrets)) {
+        if (!/^[A-Z0-9_.-]{1,80}$/.test(key)
+            || !record
+            || typeof record !== "object"
+            || record.key !== key
+            || typeof record.value !== "string"
+            || typeof record.createdAt !== "string"
+            || typeof record.updatedAt !== "string") {
+            throw new Error(`Secret record is malformed: ${key}`);
+        }
+    }
+}
+function assertPassphrase(passphrase) {
+    if (passphrase.length < 8) {
+        throw new Error("Secret bundle passphrase must be at least 8 characters.");
+    }
+}
+function decodeBase64(value, label) {
+    const decoded = Buffer.from(value, "base64");
+    if (decoded.length === 0) {
+        throw new Error(`Secret bundle ${label} is empty or invalid.`);
+    }
+    return decoded;
+}
+function deriveKey(passphrase, salt) {
+    return new Promise((resolve, reject) => {
+        scrypt(passphrase, salt, 32, (error, key) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(key);
+        });
+    });
+}
+async function atomicWrite(filePath, content, mode) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.writeFile(tempPath, content, { encoding: "utf8", mode });
+        await fs.chmod(tempPath, mode).catch(() => undefined);
+        await fs.rename(tempPath, filePath);
+        await fs.chmod(filePath, mode).catch(() => undefined);
+    }
+    finally {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+    }
+}

package/dist/telegram-command-menu.js

@@ -11,7 +11,7 @@ export const TELEGRAM_COMMAND_MENU = [
     { command: "attach", description: "Attach an existing provider session" },
     { command: "state", description: "Show or edit session state notes" },
     { command: "option", description: "Show or change runtime options" },
-    { command: "secret", description: "Store or manage hidden secret values" },
+    { command: "secret", description: "Store, export, or manage hidden secrets" },
     { command: "docs", description: "Pin or find session documents" },
     { command: "macro", description: "Save or run reusable instructions" },
     { command: "model", description: "Show or change provider model" },

package/docs/CLI_BOOTSTRAP_AND_SECRET_MIGRATION.md

@@ -0,0 +1,98 @@
+# CLI bootstrap and secret migration
+
+## First Telegram bot
+
+Install RemoteAgent, seed its runtime configuration, and register the first Telegram bot:
+
+```bash
+npm install -g appback-remoteagent
+remoteagent-install
+remoteagent bot add
+remoteagent-start
+```
+
+`remoteagent bot add` asks for the BotFather token without echoing it and then asks for the numeric Telegram owner user ID. It validates the token with Telegram `getMe` before writing `~/.remoteagent/.env`.
+
+For automation, keep sensitive values out of shell history by using a permission-restricted token file:
+
+```bash
+chmod 600 /secure/path/telegram-token
+remoteagent bot add --token-file /secure/path/telegram-token --owner 123456789
+```
+
+After adding or updating a bot, apply the configuration with the runtime command appropriate to the installation:
+
+```bash
+remoteagent-start
+```
+
+```bash
+sudo systemctl restart remoteagent
+```
+
+## Secret migration
+
+RemoteAgent `/secret` values belong to the installation, not to an individual agent session. They are stored under `~/.remoteagent/managed/secrets.json`.
+
+Export them on the old PC as a password-encrypted bundle:
+
+```bash
+remoteagent secret export ~/remoteagent-secrets.ra-secrets
+```
+
+The command asks twice for a bundle passphrase. The resulting file uses scrypt key derivation and AES-256-GCM authenticated encryption; secret values are never printed.
+
+Transfer the encrypted file to the new PC, install RemoteAgent, and import it:
+
+```bash
+remoteagent-install
+remoteagent secret import ~/remoteagent-secrets.ra-secrets
+```
+
+Import merges the bundle into the new PC's installation-wide Secret store. Imported keys replace keys with the same name; unrelated existing keys remain. Before overwriting an existing store, RemoteAgent creates a permission-restricted timestamped backup beside `secrets.json`.
+
+Use `--replace` only when the imported bundle must become the entire Secret store:
+
+```bash
+remoteagent secret import ~/remoteagent-secrets.ra-secrets --replace
+```
+
+For non-interactive automation, provide a permission-restricted passphrase file:
+
+```bash
+chmod 600 /secure/path/transfer-passphrase
+remoteagent secret export ~/remoteagent-secrets.ra-secrets --passphrase-file /secure/path/transfer-passphrase
+remoteagent secret import ~/remoteagent-secrets.ra-secrets --passphrase-file /secure/path/transfer-passphrase
+```
+
+The Telegram bot token and `TELEGRAM_OWNER_ID` are runtime configuration, not `/secret` values. Register the bot separately with `remoteagent bot add` on the new PC.
+
+## Encrypted delivery through Telegram
+
+RemoteAgent can send selected Secret values back to the current private chat without exposing their values to the provider or Telegram message text. First store a transfer passphrase that you know:
+
+```text
+/secret set REMOTEAGENT_TRANSFER_PASSPHRASE a-long-private-passphrase
+```
+
+Then export only the required keys:
+
+```text
+/secret export REMOTEAGENT_TRANSFER_PASSPHRASE APPBACK_RELEASE_STORE_PASSWORD APPBACK_RELEASE_KEY_PASSWORD APPBACK_RELEASE_KEYSTORE_BASE64 GOOGLE_PLAY_SERVICE_ACCOUNT_JSON
+```
+
+RemoteAgent performs these steps itself:
+
+1. Reads the passphrase and selected Secret values without sending them to Codex or Claude.
+2. Excludes the passphrase key from the bundle.
+3. Compresses the payload with gzip and encrypts it with AES-256-GCM.
+4. Sends the `.ra-secrets` file to the same Telegram chat.
+5. Removes the temporary server-side bundle after delivery.
+
+Import the received file on the destination PC with the CLI:
+
+```bash
+remoteagent secret import ~/Downloads/remoteagent-secrets-S001-20260811.ra-secrets
+```
+
+The `/secret set` source message is deleted from the private chat after successful storage when Telegram permits deletion, and local RemoteAgent logs redact its value. Telegram bot chats are not end-to-end encrypted, so the local CLI export remains the strongest option for especially sensitive credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appback-remoteagent",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Personal installable session server for continuing local AI work across PC and Telegram",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "check": "tsc --noEmit -p tsconfig.json",
     "selftest:telegram": "npm run build && node scripts/selftest-telegram-update.mjs",
     "selftest:codex-stream": "npm run build && node scripts/selftest-codex-stream.mjs",
+    "selftest:cli": "npm run build && node scripts/selftest-cli.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "node scripts/prepublish-guard.mjs",
     "release:version": "bash scripts/release-version.sh",

package/scripts/install.sh

@@ -45,6 +45,13 @@ fi
 
 mkdir -p "$DATA_DIR" "$DATA_DIR/logs"
 
+NODE_BIN_PATH="$(command -v node || true)"
+if [ -z "$NODE_BIN_PATH" ]; then
+  echo "node is required to install RemoteAgent." >&2
+  exit 1
+fi
+NODE_BIN_DIR="$(cd -P "$(dirname "$NODE_BIN_PATH")" && pwd)"
+
 if [ ! -f "$ENV_FILE" ]; then
   cp "$ROOT_DIR/.env.example" "$ENV_FILE"
   echo "Created $ENV_FILE"
@@ -84,6 +91,8 @@ upsert_env "BOT_RESTART_HELPER_PATH" "$ROOT_DIR/scripts/restart-after-bot-op.sh"
 
 cat > "$DATA_DIR/start-remoteagent.sh" <<EOF
 #!/usr/bin/env bash
+export PATH="$NODE_BIN_DIR:\$PATH"
+export NODE_BIN="$NODE_BIN_PATH"
 DATA_DIR="$DATA_DIR" "$ROOT_DIR/scripts/start.sh"
 EOF
 chmod +x "$DATA_DIR/start-remoteagent.sh"

package/scripts/selftest-cli.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { registerTelegramBot } from "../dist/services/cli-config-service.js";
+import { exportSecrets, importSecrets } from "../dist/services/secret-transfer-service.js";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "remoteagent-cli-selftest-"));
+const sourceDataDir = path.join(root, "source");
+const targetDataDir = path.join(root, "target");
+const bundlePath = path.join(root, "transfer.ra-secrets");
+const selectedBundlePath = path.join(root, "selected-transfer.ra-secrets");
+const passphrase = "correct-horse-battery-staple";
+
+try {
+  await fs.mkdir(sourceDataDir, { recursive: true });
+  await fs.writeFile(path.join(sourceDataDir, ".env"), [
+    "TELEGRAM_BOT_TOKEN=your-telegram-bot-token",
+    "TELEGRAM_BOT_TOKENS=",
+    "TELEGRAM_OWNER_ID=",
+    "DEFAULT_MODE=codex",
+    "",
+  ].join("\n"), { mode: 0o600 });
+
+  const first = await registerTelegramBot({
+    dataDir: sourceDataDir,
+    token: "100001:abcdefghijklmnopqrstuvwxyz_123456",
+    ownerId: "8202993989",
+    identity: { id: 100001, username: "first_remoteagent_bot" },
+  });
+  assert.equal(first.added, true);
+  assert.equal(first.botCount, 1);
+
+  const second = await registerTelegramBot({
+    dataDir: sourceDataDir,
+    token: "100002:abcdefghijklmnopqrstuvwxyz_654321",
+    ownerId: "8202993989",
+    identity: { id: 100002, username: "second_remoteagent_bot" },
+  });
+  assert.equal(second.botCount, 2);
+  const envText = await fs.readFile(path.join(sourceDataDir, ".env"), "utf8");
+  assert.match(envText, /DEFAULT_MODE=codex/);
+  assert.match(envText, /TELEGRAM_OWNER_ID=8202993989/);
+  assert.doesNotMatch(envText, /your-telegram-bot-token/);
+  assert.match(envText, /TELEGRAM_BOT_USERNAMES=first_remoteagent_bot,second_remoteagent_bot/);
+
+  const sourceSecrets = {
+    API_TOKEN: {
+      key: "API_TOKEN",
+      value: "plain-value-must-not-appear-in-bundle",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    },
+    DB_PASSWORD: {
+      key: "DB_PASSWORD",
+      value: "another-private-value",
+      createdAt: "2026-01-02T00:00:00.000Z",
+      updatedAt: "2026-01-02T00:00:00.000Z",
+    },
+  };
+  await fs.mkdir(path.join(sourceDataDir, "managed"), { recursive: true });
+  await fs.writeFile(
+    path.join(sourceDataDir, "managed", "secrets.json"),
+    `${JSON.stringify(sourceSecrets, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+
+  const exported = await exportSecrets(sourceDataDir, bundlePath, passphrase);
+  assert.equal(exported.count, 2);
+  const bundleText = await fs.readFile(bundlePath, "utf8");
+  assert.doesNotMatch(bundleText, /plain-value-must-not-appear-in-bundle/);
+  assert.doesNotMatch(bundleText, /another-private-value/);
+  assert.match(bundleText, /remoteagent-secret-bundle/);
+  assert.match(bundleText, /"compression": "gzip"/);
+
+  const selectedExport = await exportSecrets(sourceDataDir, selectedBundlePath, passphrase, {
+    includeKeys: ["API_TOKEN"],
+  });
+  assert.equal(selectedExport.count, 1);
+  const selectedDataDir = path.join(root, "selected-target");
+  await importSecrets(selectedDataDir, selectedBundlePath, passphrase);
+  const selectedSecrets = JSON.parse(await fs.readFile(path.join(selectedDataDir, "managed", "secrets.json"), "utf8"));
+  assert.deepEqual(Object.keys(selectedSecrets), ["API_TOKEN"]);
+
+  await fs.mkdir(path.join(targetDataDir, "managed"), { recursive: true });
+  await fs.writeFile(path.join(targetDataDir, "managed", "secrets.json"), JSON.stringify({
+    API_TOKEN: {
+      key: "API_TOKEN",
+      value: "old-value",
+      createdAt: "2025-01-01T00:00:00.000Z",
+      updatedAt: "2025-01-01T00:00:00.000Z",
+    },
+    KEEP_ME: {
+      key: "KEEP_ME",
+      value: "kept-value",
+      createdAt: "2025-01-01T00:00:00.000Z",
+      updatedAt: "2025-01-01T00:00:00.000Z",
+    },
+  }, null, 2), { mode: 0o600 });
+
+  const imported = await importSecrets(targetDataDir, bundlePath, passphrase);
+  assert.equal(imported.imported, 2);
+  assert.equal(imported.overwritten, 1);
+  assert.equal(imported.total, 3);
+  assert.ok(imported.backupPath);
+  const importedSecrets = JSON.parse(await fs.readFile(path.join(targetDataDir, "managed", "secrets.json"), "utf8"));
+  assert.equal(importedSecrets.API_TOKEN.value, sourceSecrets.API_TOKEN.value);
+  assert.equal(importedSecrets.DB_PASSWORD.value, sourceSecrets.DB_PASSWORD.value);
+  assert.equal(importedSecrets.KEEP_ME.value, "kept-value");
+
+  await assert.rejects(
+    importSecrets(path.join(root, "wrong-passphrase"), bundlePath, "wrong-passphrase"),
+    /could not be decrypted/,
+  );
+
+  console.log("RemoteAgent CLI self-test passed.");
+} finally {
+  await fs.rm(root, { recursive: true, force: true });
+}

package/scripts/selftest-telegram-update.mjs

@@ -11,6 +11,7 @@ const workspace = path.join(tmp, "workspace");
 const workspaceRoot = path.join(tmp, "workspaces");
 const binDir = path.join(tmp, "bin");
 const telegramCalls = path.join(tmp, "telegram-calls.jsonl");
+const capturedDocument = path.join(tmp, "captured-document.ra-secrets");
 
 await fs.mkdir(workspace, { recursive: true });
 await fs.mkdir(workspaceRoot, { recursive: true });
@@ -22,6 +23,7 @@ method="unknown"
 text=""
 chat_id=""
 reply_markup=""
+document_path=""
 for arg in "$@"; do
   case "$arg" in
     https://api.telegram.org/bot*/sendMessage) method="sendMessage" ;;
@@ -32,6 +34,7 @@ for arg in "$@"; do
     chat_id=*) chat_id="\${arg#chat_id=}" ;;
     text=*) text="\${arg#text=}" ;;
     reply_markup=*) reply_markup="\${arg#reply_markup=}" ;;
+    document=@*) document_path="\${arg#document=@}" ;;
   esac
 done
 text_b64="$(printf '%s' "$text" | base64 -w 0)"
@@ -45,6 +48,7 @@ case "$method" in
     printf '{"ok":true,"result":true}'
     ;;
   sendDocument)
+    cp "$document_path" ${JSON.stringify(capturedDocument)}
     printf '{"ok":true,"result":{"message_id":1002,"document":{"file_id":"fake"}}}'
     ;;
   *)
@@ -72,6 +76,7 @@ const [
   { BotManagementService },
   { FileStore },
   { AgentMemoryService },
+  { importSecrets },
   { WorkspaceCleanupService },
   { buildFallbackBotInfo },
 ] = await Promise.all([
@@ -80,6 +85,7 @@ const [
   import(path.join(root, "dist", "services", "bot-management-service.js")),
   import(path.join(root, "dist", "store", "file-store.js")),
   import(path.join(root, "dist", "services", "agent-memory-service.js")),
+  import(path.join(root, "dist", "services", "secret-transfer-service.js")),
   import(path.join(root, "dist", "services", "workspace-cleanup-service.js")),
   import(path.join(root, "dist", "telegram-bot-identity.js")),
 ]);
@@ -295,6 +301,9 @@ await send("/start codex");
 await send("/option retry 6");
 await send("/option timeout 600");
 await send("/option intent 4");
+await send("/secret set REMOTEAGENT_TRANSFER_PASSPHRASE correct-horse-battery-staple");
+await send("/secret set API_TOKEN telegram-secret-export-value");
+await send("/secret export REMOTEAGENT_TRANSFER_PASSPHRASE API_TOKEN");
 await send("같은 값을 봐야하는데 로직문제네? 확인해줘\\n이미 수정되어 있을 수 있어.\\n나한테 수정했다고 보고했었거든");
 await send("/state");
 
@@ -318,6 +327,32 @@ if (!/^TELEGRAM_UNTAGGED_INTENT_RETRIES=4$/m.test(envText)) {
   throw new Error(`Option command did not persist untagged intent retry limit to .env: ${envText}`);
 }
 
+const importedSecretDataDir = path.join(tmp, "imported-secret-data");
+const importedSecretResult = await importSecrets(
+  importedSecretDataDir,
+  capturedDocument,
+  "correct-horse-battery-staple",
+);
+if (importedSecretResult.imported !== 1) {
+  throw new Error(`Expected one Telegram-exported Secret, got ${importedSecretResult.imported}`);
+}
+const importedSecretStore = JSON.parse(
+  await fs.readFile(path.join(importedSecretDataDir, "managed", "secrets.json"), "utf8"),
+);
+if (importedSecretStore.API_TOKEN?.value !== "telegram-secret-export-value") {
+  throw new Error("Telegram Secret export did not preserve the selected Secret value");
+}
+if (importedSecretStore.REMOTEAGENT_TRANSFER_PASSPHRASE) {
+  throw new Error("Telegram Secret export included its transfer passphrase key");
+}
+const secretTelegramCalls = await readTelegramCalls();
+if (secretTelegramCalls.filter((call) => call.method === "deleteMessage").length < 2) {
+  throw new Error("Secret source messages were not deleted after storage");
+}
+if (!secretTelegramCalls.some((call) => call.method === "sendDocument")) {
+  throw new Error("Encrypted Secret bundle was not sent as a Telegram document");
+}
+
 const sessionWorkspace = session.workspace;
 await fs.mkdir(path.join(sessionWorkspace, "node_modules", "left-pad"), { recursive: true });
 await fs.mkdir(path.join(sessionWorkspace, "src"), { recursive: true });