appback-remoteagent 0.17.1 → 0.20.0

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/docs/RELEASING.md

@@ -220,3 +220,25 @@ npm run selftest:telegram
 npm run release:publish
 npm run release:deploy -- 0.17.1 30
 ```
+
+## Release 0.18.0
+
+Date: 2026-08-03
+
+Changes:
+
+- Telegram list and option responses provide inline command controls.
+- Queue notices provide inline remove-latest and remove-by-id controls in one message.
+- Codex progress streaming accepts both normalized CLI `item.completed` events and raw `event_msg`/`response_item` agent-message events.
+- The Codex stream self-test covers every supported progress event shape and keeps final results out of the progress callback.
+
+Validated:
+
+```bash
+npm run check
+npm run build
+npm run selftest:codex-stream
+npm run selftest:telegram
+npm run release:publish
+npm run release:deploy -- 0.18.0 30
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appback-remoteagent",
-  "version": "0.17.1",
+  "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-codex-stream.mjs

@@ -23,7 +23,9 @@ printf '%s\\n' '{"type":"thread.started","thread_id":"stream-thread"}'
 printf '%s' '{"type":"item.completed","item":{"type":"agent_message","text":"REPORT:progress\\nphase one"}}'
 printf '\\n'
 sleep 0.05
-printf '%s\\n' '{"type":"item.completed","item":{"type":"agent_message","text":"REPORT:progress\\nphase two"}}'
+printf '%s\\n' '{"type":"event_msg","payload":{"type":"agent_message","message":"REPORT:progress\\nphase two"}}'
+sleep 0.05
+printf '%s\\n' '{"type":"response_item","payload":{"type":"message","content":[{"type":"output_text","text":"REPORT:progress\\nphase three"}]}}'
 sleep 0.05
 printf '%s\\n' '{"type":"item.completed","item":{"type":"agent_message","text":"REPORT:result\\nfinished"}}'
 printf '%s\\n' 'REPORT:result' 'finished' > "$output"
@@ -50,7 +52,12 @@ const responsePromise = adapter.send({
 const response = await responsePromise;
 settled = true;
 
-if (progress.length !== 2 || !progress[0]?.includes("phase one") || !progress[1]?.includes("phase two")) {
+if (
+  progress.length !== 3
+  || !progress[0]?.includes("phase one")
+  || !progress[1]?.includes("phase two")
+  || !progress[2]?.includes("phase three")
+) {
   throw new Error(`Unexpected streamed progress: ${JSON.stringify(progress)}`);
 }
 if (progress.some((item) => item.includes("REPORT:result"))) {

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")),
 ]);
@@ -254,6 +260,14 @@ async function click(data) {
   await injectedBot.handleUpdates([callbackUpdate(data)]);
 }
 
+function findInlineButton(call, label) {
+  if (!call?.reply_markup) {
+    return undefined;
+  }
+  const markup = JSON.parse(call.reply_markup);
+  return markup.inline_keyboard?.flat().find((button) => button.text === label);
+}
+
 async function readTelegramCalls() {
   return (await fs.readFile(telegramCalls, "utf8"))
     .trim()
@@ -287,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");
 
@@ -310,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 });
@@ -440,6 +483,83 @@ if (calls.some((call) => /미완료 TODO|\/task|새 작업으로 접수/.test(ca
   throw new Error(`Task gate language leaked to Telegram replies. Calls: ${JSON.stringify(calls, null, 2)}`);
 }
 
+await send("/new");
+await send("/list");
+const sessionListCall = await waitForTelegramCall((call) => call.text.includes("Sessions (2/2)"));
+const firstSessionButton = findInlineButton(sessionListCall, `S001 · ${path.basename(session.workspace)}`);
+if (!firstSessionButton?.callback_data?.startsWith("remoteagent:action:")) {
+  throw new Error(`Session switch button is missing: ${sessionListCall.reply_markup}`);
+}
+await click(firstSessionButton.callback_data);
+await waitForTelegramCall((call) => call.text.includes("Switched this chat to session S001."));
+
+await send("/model");
+const modelListCall = await waitForTelegramCall((call) => call.text.includes("availablePresets:"));
+const modelButton = findInlineButton(modelListCall, "gpt-5.6-terra");
+if (!modelButton?.callback_data) {
+  throw new Error(`Model selection button is missing: ${modelListCall.reply_markup}`);
+}
+await click(modelButton.callback_data);
+await waitForTelegramCall((call) => call.text.includes("Set codex model to gpt-5.6-terra."));
+const modelState = JSON.parse(await fs.readFile(path.join(dataDir, "state.json"), "utf8"));
+if (modelState.sessions[session.sessionId]?.codex?.model !== "gpt-5.6-terra") {
+  throw new Error("Model button did not update the bound session model");
+}
+
+await send("/option");
+const optionListCall = await waitForTelegramCall((call) => call.text.startsWith("Runtime options"));
+const timeoutButton = findInlineButton(optionListCall, "Timeout");
+if (!timeoutButton?.callback_data) {
+  throw new Error(`Runtime option button is missing: ${optionListCall.reply_markup}`);
+}
+await click(timeoutButton.callback_data);
+await waitForTelegramCall((call) => call.text.includes("Current provider execution timeout: 600s"));
+
+await send("/sandbox");
+const sandboxListCall = await waitForTelegramCall((call) => call.text.startsWith("Codex sandbox"));
+const readOnlyButton = findInlineButton(sandboxListCall, "read-only");
+const dangerButton = findInlineButton(sandboxListCall, "danger-full-access");
+if (!readOnlyButton?.callback_data || !dangerButton?.callback_data) {
+  throw new Error(`Sandbox selection buttons are missing: ${sandboxListCall.reply_markup}`);
+}
+await click(readOnlyButton.callback_data);
+await waitForTelegramCall((call) => call.text.includes("Set Codex sandbox to read-only."));
+await click(dangerButton.callback_data);
+const sandboxConfirmCall = await waitForTelegramCall((call) => call.text.includes("Confirm Codex sandbox change"));
+if (!findInlineButton(sandboxConfirmCall, "Confirm danger-full-access")?.callback_data) {
+  throw new Error(`Danger sandbox confirmation button is missing: ${sandboxConfirmCall.reply_markup}`);
+}
+
+await send("/macro set button-test inspect the callback path");
+await send("/batch start");
+await send("/macro");
+const macroListCall = await waitForTelegramCall((call) => call.text.includes("Macros (1)"));
+const macroButton = findInlineButton(macroListCall, "button-test");
+if (!macroButton?.callback_data) {
+  throw new Error(`Macro execution button is missing: ${macroListCall.reply_markup}`);
+}
+await click(macroButton.callback_data);
+await send("/batch send");
+await waitForTelegramCall((call) => call.text.includes("mock provider completed"));
+
+await fs.appendFile(path.join(dataDir, ".env"), [
+  "TELEGRAM_BOT_TOKENS=000000:test-token",
+  "TELEGRAM_BOT_USERNAMES=remoteagent_test_bot",
+  "",
+].join("\n"), "utf8");
+await send("/bots");
+const botsCall = await waitForTelegramCall((call) => call.text.includes("Configured bots (1)"));
+const botLink = findInlineButton(botsCall, "@bot_0");
+const refreshButton = findInlineButton(botsCall, "Refresh");
+if (botLink?.url !== "https://t.me/bot_0" || !refreshButton?.callback_data) {
+  throw new Error(`Bot link or refresh button is missing: ${botsCall.reply_markup}`);
+}
+await click(refreshButton.callback_data);
+const refreshedBotsCalls = (await readTelegramCalls()).filter((call) => call.text.includes("Configured bots (1)"));
+if (refreshedBotsCalls.length < 2) {
+  throw new Error("Bot refresh callback did not render the bot list again");
+}
+
 providerMode = "timeout";
 await send("/batch start");
 await send("timeout regression test");