connelio 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connelio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# connelio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Put your AI agent in [Connelio](https://connelio.app) and talk to it from your phone — like a contact.
+
+```bash
+npx connelio connect
+```
+
+A QR code appears in your terminal. On your phone open **Connelio → Chats → + → Connect your AI**, scan it, tap **Connect**. Your agent shows up in your chat list and says it is online. No bot tokens to copy, no BotFather.
+
+## What you get
+
+- **Claude Code in your pocket.** Each message runs Claude Code in your project folder. Every step shows up as a live progress card. When Claude wants to edit a file or run a command, your phone asks **Allow / Always in this chat / Deny** — only you can tap it.
+- **Any CLI agent.** `npx connelio connect -- <command>` sends each message to the command on stdin and replies with its stdout. Works with `codex exec`, `gemini`, `llm`, `ollama run …`, or your own script.
+- **Groups.** Add your agent to a group; it answers when someone @mentions it. Put two agents in one group and let them work together while you watch.
+- **Telegram-compatible.** Agents built on the Telegram Bot API (python-telegram-bot, grammY, aiogram, Telegraf, Hermes) connect by changing two settings: the token and the API address `https://connelio.app/tg`. See [Hermes](#hermes).
+
+## Private and public agents
+
+| | `--mode private` (default) | `--mode public` |
+| --- | --- | --- |
+| Who can use it | only you | anyone you share it with |
+| Where it works | your `--dir` (default: current folder) | an isolated folder per chat |
+| Edit files / run commands | yes, with your approval on the phone | no |
+| Reads | anything Claude Code can read | its own chat folder + an optional read-only `--knowledge` folder |
+
+**Every chat is isolated.** Each conversation gets its own folder under `~/.connelio/sessions/` and its own Claude session, so one person's chat can never see another's. In public mode, the first time someone new writes to your agent they are told it runs on your computer and that you can see what they send.
+
+## Commands
+
+```
+npx connelio connect [--mode private|public] [--dir PATH] [--knowledge PATH] [--name TEXT] [-- COMMAND ...]
+npx connelio run [name]      start a paired agent again
+npx connelio list            paired agents on this computer
+npx connelio forget <name>   delete a saved token
+```
+
+Tokens are stored in `~/.connelio/agents/` with file mode 600. `forget` removes one; resetting the agent on your phone revokes it.
+
+## Hermes
+
+One command on the computer that runs Hermes:
+
+```bash
+npx connelio connect --hermes                          # use the active Hermes profile
+npx connelio connect --hermes --hermes-profile connelio # keep your Telegram bot, add Connelio as its own profile
+```
+
+Scan the QR code, and the command writes Hermes's settings (address, token, and an allow-list with only you) through `hermes config set`, then restarts the Hermes gateway.
+
+Doing it by hand: Hermes talks to Telegram through python-telegram-bot and lets you set the API address. Create a Bot Agent in Connelio, copy its token once, then in your Hermes config:
+
+```yaml
+platforms:
+  telegram:
+    enabled: true
+    extra:
+      base_url: https://connelio.app/tg/bot
+      base_file_url: https://connelio.app/tg/file/bot
+```
+
+and set `TELEGRAM_BOT_TOKEN` to the agent's token and `TELEGRAM_ALLOWED_USERS` to your own user id.
+
+## Costs and accounts
+
+The agent runs on your computer with your own Claude Code login or API key. Connelio never sees your model credentials.
+
+## Requirements
+
+Node.js 20+. For Claude Code: the Claude Agent SDK (installed with this package) and a working Claude Code login on this computer.
+
+---
+
+# connelio（中文）
+
+把你的 AI 代理接进 Connelio，在手机上像跟联系人聊天一样指挥它。
+
+```bash
+npx connelio connect
+```
+
+终端里出一个二维码。手机打开 **Connelio → 消息 → 右上 + → 接入我的 AI**，扫码，点 **连接**。代理会出现在聊天列表里并说"已上线"。不用复制 token。
+
+- **Claude Code**：每条消息在你的项目目录里跑；每一步实时显示在进度卡上；要改文件、跑命令时手机弹「允许 / 本会话都允许 / 拒绝」，只有你能点。
+- **任意命令行代理**：`npx connelio connect -- <命令>`，消息从 stdin 进，stdout 作为回复。
+- **群聊**：把代理拉进群，有人 @ 它就回答；两个代理放一个群可以协作。
+- **兼容 Telegram**：基于 Telegram Bot API 的代理（含 Hermes）改 token 和地址两项即可接入。
+
+**私用 / 公开**：私用（默认）只有你能用，在你指定的目录里工作；公开模式谁都能聊，但每个会话一个独立目录、不能改文件和跑命令，陌生人第一次来会被告知"代理由你运行、内容你看得到"。
+
+模型费用和账号都是你自己的，Connelio 看不到你的模型密钥。

package/TRADEMARKS.md

@@ -0,0 +1,5 @@
+# Trademarks
+
+The code in this repository is MIT-licensed: use it, fork it, ship it.
+
+The MIT license does not cover the **Connelio** name or logo. You may say your project "works with Connelio" or "connects to Connelio", but please do not use the name or logo in a way that suggests your project is made or endorsed by Connelio.

package/bin/connelio.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// connelio — 把你的 AI 代理接进 Connelio：扫码配对，手机上像聊天一样指挥它。
+import { resolve } from 'node:path';
+import { createApi } from '../src/api.mjs';
+import { listAgents, loadAgent, removeAgent, saveAgent } from '../src/config.mjs';
+import { pair } from '../src/pair.mjs';
+import { runAgent } from '../src/runner.mjs';
+import { claudeCodeAdapter } from '../src/adapters/claude-code.mjs';
+import { commandAdapter } from '../src/adapters/command.mjs';
+import { configureHermes, hermesCli } from '../src/hermes.mjs';
+
+const HELP = `connelio — put your AI agent in Connelio
+
+  npx connelio connect                 pair Claude Code in this folder (scan the QR with Connelio on your phone)
+  npx connelio connect --hermes        connect the Hermes agent on this computer (writes its config, restarts it)
+  npx connelio connect -- <command>    pair any CLI agent: each message goes to <command> on stdin, stdout is the reply
+  npx connelio run [name]              start a paired agent again (no new pairing)
+  npx connelio list                    show paired agents on this computer
+  npx connelio forget <name>           remove a paired agent's saved token from this computer
+
+Options for connect:
+  --mode private|public   private (default): only you can use it, it works in --dir with your approval on the phone
+                          public: anyone you share it with can chat; each chat is isolated, no file changes or commands
+  --dir <path>            project folder for private mode (default: current folder)
+  --knowledge <path>      read-only folder that public chats may read
+  --name <text>           how this computer is shown on your phone
+  --server <url>          Connelio server (default https://connelio.app)
+  --hermes-profile <name> with --hermes: use (or create) this Hermes profile instead of the active one
+  --replace               with --hermes: replace the Telegram bot this Hermes profile already uses
+`;
+
+function parse(argv) {
+  const dash = argv.indexOf('--');
+  const head = dash >= 0 ? argv.slice(0, dash) : argv;
+  const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  const [verb, ...rest] = head;
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg.startsWith('--')) {
+      const [key, inline] = arg.slice(2).split('=');
+      flags[key] = inline ?? (rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[++i] : true);
+    } else positional.push(arg);
+  }
+  return { verb, flags, positional, command };
+}
+
+async function adapterFor(config) {
+  return config.command?.length ? commandAdapter(config.command) : claudeCodeAdapter();
+}
+
+async function start(config) {
+  const controller = new AbortController();
+  const stop = () => { controller.abort(); process.stdout.write('\n[connelio] stopped.\n'); setTimeout(() => process.exit(0), 200).unref(); };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  const api = createApi({ apiBase: config.apiBase, token: config.token, consumerId: `bridge-${config.deviceName ?? 'local'}`.slice(0, 64) });
+  const adapter = await adapterFor(config);
+  await runAgent({ api, config, adapter, signal: controller.signal });
+  saveAgent(config);
+}
+
+async function main() {
+  const { verb, flags, positional, command } = parse(process.argv.slice(2));
+  if (!verb || verb === 'help' || flags.help || flags.h) { process.stdout.write(HELP); return; }
+  const server = String(flags.server || process.env.CONNELIO_SERVER || 'https://connelio.app');
+
+  if (verb === 'connect' && flags.hermes) {
+    const profile = typeof flags['hermes-profile'] === 'string' ? flags['hermes-profile'] : '';
+    const hermes = hermesCli(profile);
+    if (!hermes.available()) throw new Error('Hermes was not found on this computer (`hermes --version` failed). Install Hermes first: https://hermes-agent.nousresearch.com');
+    hermes.ensureProfile();
+    if (hermes.existingTelegramToken() && !flags.replace) {
+      throw new Error(`This Hermes profile already talks to a Telegram bot. Keep it and add Connelio as a separate profile:\n  npx connelio connect --hermes --hermes-profile connelio\nor replace it:\n  npx connelio connect --hermes --replace`);
+    }
+    const result = await pair({ server, kind: 'hermes', deviceName: typeof flags.name === 'string' ? flags.name : undefined });
+    configureHermes({ hermes, server, token: result.token, ownerTelegramId: result.owner?.telegramId });
+    process.stdout.write(`✓ Hermes is now connected as ${result.bot.displayName} (@${result.bot.username}).\n`);
+    if (hermes.restart()) process.stdout.write('✓ Hermes gateway restarted. Say hi to it in Connelio.\n');
+    else process.stdout.write(`Start Hermes to go online:  hermes${profile ? ` -p ${profile}` : ''} gateway run\n`);
+    return;
+  }
+  if (verb === 'connect') {
+    const mode = flags.mode === 'public' ? 'public' : 'private';
+    const kind = command.length ? 'generic' : 'claude-code';
+    if (!command.length) await claudeCodeAdapter();   // 先确认本机能跑 Claude Code，再去配对，避免配完才报错
+    const result = await pair({ server, kind, deviceName: typeof flags.name === 'string' ? flags.name : undefined });
+    const config = {
+      apiBase: server.replace(/\/+$/, ''), token: result.token, bot: result.bot, owner: result.owner,
+      conversationId: result.conversationId, deviceName: typeof flags.name === 'string' ? flags.name : undefined,
+      kind, mode, command,
+      dir: mode === 'private' ? resolve(typeof flags.dir === 'string' ? flags.dir : process.cwd()) : null,
+      knowledge: typeof flags.knowledge === 'string' ? resolve(flags.knowledge) : null,
+    };
+    const file = saveAgent(config);
+    process.stdout.write(`✓ Paired as ${result.bot.displayName} (@${result.bot.username}). Saved to ${file}\n`);
+    if (flags['no-run']) return;
+    await start(config);
+    return;
+  }
+  if (verb === 'run') {
+    const config = loadAgent(positional[0]);
+    if (!config) throw new Error(positional[0] ? `No paired agent named ${positional[0]}.` : 'Pick one: `npx connelio run <name>` (see `npx connelio list`).');
+    await start(config);
+    return;
+  }
+  if (verb === 'list') {
+    const agents = listAgents();
+    if (!agents.length) process.stdout.write('No paired agents. Run `npx connelio connect`.\n');
+    for (const a of agents) process.stdout.write(`${a.bot.username}\t${a.bot.displayName}\t${a.mode}\t${a.command?.length ? a.command.join(' ') : 'claude-code'}\n`);
+    return;
+  }
+  if (verb === 'forget') {
+    if (!positional[0]) throw new Error('Usage: npx connelio forget <name>');
+    process.stdout.write(removeAgent(positional[0]) ? 'Removed.\n' : 'Not found.\n');
+    return;
+  }
+  process.stdout.write(HELP);
+  process.exitCode = 1;
+}
+
+main().catch((error) => { process.stderr.write(`connelio: ${error?.message || error}\n`); process.exit(1); });

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "connelio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Put your AI agent (Claude Code, Hermes, any CLI) in Connelio: pair with a QR code, chat with it from your phone.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "connelio": "bin/connelio.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "TRADEMARKS.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "qrcode": "1.5.4"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.318"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "connelio",
+    "claude-code",
+    "hermes",
+    "agent",
+    "telegram",
+    "remote-control",
+    "chat"
+  ]
+}

package/src/adapters/claude-code.mjs

@@ -0,0 +1,110 @@
+// Claude Code 适配器：用官方 Claude Agent SDK 在本机跑 Claude Code。
+// - 每个会话独立的 Claude 会话（resume 上次的 session_id），历史互不可见。
+// - 进度：工具调用一步一行，回到手机上的进度卡。
+// - 权限：Claude 要改文件 / 跑命令时，手机上弹「允许 / 本会话都允许 / 拒绝」，只有主人能点。
+// - public 模式：不给改文件、跑命令的工具；最多只读本会话目录和 --knowledge 指定的只读资料目录。
+// 用的是你本机 Claude Code 的登录 / API key，费用和额度都是你自己的。
+import { resolve, sep } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+const READ_ONLY = ['Read', 'Grep', 'Glob'];
+// public 模式只给 Claude 认证真正需要的环境变量；其余（可能含主人机器上的密钥）一律不带。
+const PUBLIC_ENV_KEEP = ['PATH', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR', 'SYSTEMROOT', 'COMSPEC',
+  'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL',
+  'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR'];
+
+const real = (p) => { try { return realpathSync(p); } catch { return null; } };
+const hasMagic = (part) => /[*?[\]{}]/.test(part);
+
+export async function claudeCodeAdapter({ sdk } = {}) {
+  try { sdk ??= await import('@anthropic-ai/claude-agent-sdk'); }
+  catch {
+    throw new Error('Claude Agent SDK is not installed. Run `npm i -g @anthropic-ai/claude-agent-sdk` (or reinstall connelio) and make sure Claude Code is logged in.');
+  }
+  return {
+    name: 'claude-code',
+    async run(ctx) {
+      const state = ctx.state();
+      const allowedAlways = new Set(state.alwaysAllow ?? []);
+      // 根目录本身也解析成真实路径（macOS 的 /tmp、/var 都是软链接，字符串前缀比较会全判错）
+      const roots = [ctx.dir, ...(ctx.knowledge ? [ctx.knowledge] : [])].map((p) => resolve(p)).map(real).filter(Boolean);
+      const underRoots = (full) => Boolean(full) && roots.some((root) => full === root || full.startsWith(root + sep));
+      // 目标必须先真实存在：软链接按其指向算（知识目录里放一个指向 ~/.ssh 的软链接不能读出去）
+      const inRoots = (p) => typeof p === 'string' && p !== '' && underRoots(real(resolve(ctx.cwd, p)));
+      // Glob 的 pattern 带通配符，realpath 整串会失败：取第一段通配符之前的目录（相对路径按 cwd 解析，
+      // 绝对路径原样），解析成真实路径再比。pattern 不存在 / 解析不出来 → 拒绝。
+      const globRoot = (pattern) => {
+        if (typeof pattern !== 'string' || pattern === '') return null;
+        const full = resolve(ctx.cwd, pattern);
+        const parts = full.split(sep);
+        const at = parts.findIndex(hasMagic);
+        const base = at === -1 ? full : (parts.slice(0, at).join(sep) || sep);
+        return real(base);
+      };
+      const isPublic = ctx.mode === 'public';
+      const prompt = [ctx.text, ...ctx.attachments.map((p) => `(The user attached a file, saved at ${p})`)].filter(Boolean).join('\n\n');
+
+      const options = {
+        cwd: ctx.cwd,
+        resume: state.claudeSessionId || undefined,
+        permissionMode: 'default',
+        // 对外代理：只读工具，且只在本会话目录 / 知识库目录内；不读主人的用户级设置（避免带出主人的 MCP、记忆等）
+        ...(isPublic ? { tools: ctx.knowledge ? READ_ONLY : [], settingSources: [], additionalDirectories: ctx.knowledge ? [ctx.knowledge] : [] }
+          : { settingSources: ['user', 'project', 'local'] }),
+        // private：主人自己的机器，本来就用这份环境。
+        // public：对外代理，只给 Claude 认证需要的那几项 + PATH/HOME（HOME 指会话目录，不把主人的家目录交出去）；
+        // 登录凭据仍从主人自己的 Claude 配置目录读（订阅登录不会因此失效）。
+        env: isPublic
+          ? { ...Object.fromEntries(PUBLIC_ENV_KEEP.filter((k) => process.env[k]).map((k) => [k, process.env[k]])),
+              HOME: ctx.dir,
+              CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR || resolve(process.env.HOME || ctx.dir, '.claude'),
+              CONNELIO_SESSION_DIR: ctx.dir,
+              CLAUDE_AGENT_SDK_CLIENT_APP: 'connelio-bridge/0.1.0' }
+          : { ...process.env, CLAUDE_AGENT_SDK_CLIENT_APP: 'connelio-bridge/0.1.0' },
+        canUseTool: async (toolName, input) => {
+          if (isPublic) {
+            if (!READ_ONLY.includes(toolName)) return { behavior: 'deny', message: 'This agent is in public mode: no file changes or commands.' };
+            const allowed = toolName === 'Glob'
+              ? underRoots(globRoot(input.pattern))            // pattern 可能是绝对路径 / 含通配符
+              : inRoots(input.file_path ?? input.path ?? ctx.cwd);
+            return allowed ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: 'Outside the allowed folders.' };
+          }
+          if (allowedAlways.has(toolName)) return { behavior: 'allow', updatedInput: input };
+          const decision = await ctx.askApproval(`Claude wants to use ${toolName}`, describe(toolName, input));
+          if (decision === 'always') {
+            allowedAlways.add(toolName);
+            ctx.setState({ alwaysAllow: [...allowedAlways] });
+          }
+          return decision === 'deny' ? { behavior: 'deny', message: 'The owner denied this on their phone.' } : { behavior: 'allow', updatedInput: input };
+        },
+      };
+
+      let finalText = '';
+      let lastAssistant = '';
+      for await (const message of sdk.query({ prompt, options })) {
+        if (message.type === 'system' && message.subtype === 'init' && message.session_id) ctx.setState({ claudeSessionId: message.session_id });
+        if (message.type === 'assistant') {
+          for (const block of message.message?.content ?? []) {
+            if (block.type === 'text' && block.text) lastAssistant = block.text;
+            if (block.type === 'tool_use') ctx.progress.step(`${block.name} ${describe(block.name, block.input)}`.trim());
+          }
+        }
+        if (message.type === 'result') {
+          if (message.session_id) ctx.setState({ claudeSessionId: message.session_id });
+          if (message.subtype === 'success') finalText = message.result || lastAssistant;
+          else throw new Error(message.subtype === 'error_max_turns' ? 'Stopped: too many steps.' : 'Claude Code stopped with an error.');
+        }
+      }
+      return { text: finalText || lastAssistant || '(done)' };
+    },
+  };
+}
+
+function describe(tool, input = {}) {
+  if (input.command) return String(input.command).slice(0, 200);
+  if (input.file_path) return String(input.file_path);
+  if (input.pattern) return String(input.pattern).slice(0, 120);
+  if (input.url) return String(input.url).slice(0, 200);
+  if (input.description) return String(input.description).slice(0, 160);
+  return '';
+}

package/src/adapters/command.mjs

@@ -0,0 +1,42 @@
+// 通用命令行适配器：`npx connelio connect -- <命令> [参数…]`
+// 每条消息启动一次该命令，消息正文从 stdin 进、stdout 作为回复。工作目录 = 本会话的隔间（或主人指定的项目目录）。
+// 适合任何"读 stdin、写 stdout"的工具：codex exec、gemini、llm、ollama run、自己写的脚本……
+import { spawn } from 'node:child_process';
+
+export function commandAdapter(argv) {
+  if (!argv.length) throw new Error('No command given after `--`.');
+  return {
+    name: argv[0],
+    async run(ctx) {
+      const prompt = [ctx.text, ...ctx.attachments.map((p) => `[attached file: ${p}]`)].filter(Boolean).join('\n');
+      ctx.progress.step(`${argv[0]} started`);
+      return new Promise((resolve, reject) => {
+        const child = spawn(argv[0], argv.slice(1), {
+          cwd: ctx.cwd,
+          // 只给必要的环境：不把本机所有环境变量（可能含密钥）原样交给对外代理
+          env: ctx.mode === 'public' ? minimalEnv(ctx) : { ...process.env, ...connelioEnv(ctx) },
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let out = '', err = '';
+        child.stdout.on('data', (chunk) => { out += chunk; });
+        child.stderr.on('data', (chunk) => { err += chunk; });
+        child.on('error', reject);
+        child.on('close', (code) => {
+          if (code === 0) resolve({ text: out.trim() || '(no output)' });
+          else reject(new Error(`${argv[0]} exited with ${code}${err ? `: ${err.trim().slice(-400)}` : ''}`));
+        });
+        // 命令可能根本不读 stdin、早早退出（比如 pwd）：写管道会 EPIPE，不能让它把整个桥打崩
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(prompt);
+      });
+    },
+  };
+}
+
+function connelioEnv(ctx) {
+  return { CONNELIO_CONVERSATION_ID: ctx.conversationId, CONNELIO_SENDER: ctx.sender?.username ?? '', CONNELIO_IS_OWNER: ctx.isOwner ? '1' : '0', CONNELIO_SESSION_DIR: ctx.dir };
+}
+function minimalEnv(ctx) {
+  const keep = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR', 'SYSTEMROOT', 'COMSPEC'];
+  return { ...Object.fromEntries(keep.filter((k) => process.env[k]).map((k) => [k, process.env[k]])), HOME: ctx.dir, ...connelioEnv(ctx) };
+}

package/src/api.mjs

@@ -0,0 +1,47 @@
+// Connelio Bot API 客户端（原生 /api/bot/v1/*）。只用 Node 自带 fetch，不依赖第三方。
+
+export class ConnelioApiError extends Error {
+  constructor(status, code, detail) {
+    super(`${status} ${code}${detail ? ` (${detail})` : ''}`);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function createApi({ apiBase, token, consumerId = 'connelio-bridge' }) {
+  const base = apiBase.replace(/\/+$/, '');
+  async function call(method, body, { get = false, signal } = {}) {
+    const response = await fetch(`${base}/api/bot/v1/${method}`, {
+      method: get ? 'GET' : 'POST',
+      headers: { authorization: `Bearer ${token}`, 'x-bot-consumer': consumerId, ...(body instanceof FormData || !body ? {} : { 'content-type': 'application/json' }) },
+      body: body instanceof FormData ? body : body ? JSON.stringify(body) : undefined,
+      signal,
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok || payload.ok === false) throw new ConnelioApiError(response.status, payload.error || `HTTP_${response.status}`, payload.detail);
+    return payload;
+  }
+  return {
+    base,
+    getMe: async () => (await call('getMe', null, { get: true })).result,
+    getUpdates: async ({ offset = 0, timeout = 25, signal } = {}) => call('getUpdates', { offset, timeout, limit: 50, consumerId }, { signal }),
+    sendMessage: async (conversationId, text, replyMarkup) =>
+      (await call('sendMessage', { conversationId, text, ...(replyMarkup ? { reply_markup: replyMarkup } : {}) })).result,
+    editMessage: async (messageId, fields) => call('editMessage', { messageId, ...fields }),
+    editButtons: async (messageId, replyMarkup) => call('editMessageReplyMarkup', { messageId, reply_markup: replyMarkup }),
+    typing: async (conversationId) => call('sendChatAction', { conversationId, action: 'typing' }).catch(() => undefined),
+    answerCallback: async (callbackQueryId, text) => call('answerCallbackQuery', { callbackQueryId, text }).catch(() => undefined),
+    sendDocument: async (conversationId, filename, bytes, caption) => {
+      const form = new FormData();
+      form.set('conversationId', conversationId);
+      if (caption) form.set('caption', caption);
+      form.set('file', new Blob([bytes]), filename);
+      return (await call('sendDocument', form)).result;
+    },
+    download: async (path) => {
+      const response = await fetch(`${base}${path}`, { headers: { authorization: `Bearer ${token}` } });
+      if (!response.ok) throw new ConnelioApiError(response.status, 'DOWNLOAD_FAILED');
+      return Buffer.from(await response.arrayBuffer());
+    },
+  };
+}

package/src/config.mjs

@@ -0,0 +1,51 @@
+// 本机保存的代理凭据：~/.connelio/agents/<username>.json，权限 600。token 只存在这里。
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const home = () => process.env.CONNELIO_HOME || join(homedir(), '.connelio');
+const agentsDir = () => join(home(), 'agents');
+
+export function saveAgent(config) {
+  mkdirSync(agentsDir(), { recursive: true, mode: 0o700 });
+  const file = join(agentsDir(), `${config.bot.username}.json`);
+  writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return file;
+}
+
+export function loadAgent(name) {
+  const dir = agentsDir();
+  if (!existsSync(dir)) return null;
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const pick = name ? files.find((f) => f === `${name}.json` || f === `${name}-agent.json`) : files.length === 1 ? files[0] : null;
+  return pick ? JSON.parse(readFileSync(join(dir, pick), 'utf8')) : null;
+}
+
+export function listAgents() {
+  const dir = agentsDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')));
+}
+
+export function removeAgent(name) {
+  const file = join(agentsDir(), `${name}.json`);
+  if (!existsSync(file)) return false;
+  rmSync(file);
+  return true;
+}
+
+/** 每个会话一个隔间：独立工作目录 + 独立状态（对话历史 id 等），互相看不见。 */
+export function sessionDir(username, conversationId) {
+  const safe = String(conversationId).replace(/[^A-Za-z0-9-]/g, '');
+  const dir = join(home(), 'sessions', username, safe);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+export function readState(dir) {
+  try { return JSON.parse(readFileSync(join(dir, '.connelio-state.json'), 'utf8')); } catch { return {}; }
+}
+export function writeState(dir, state) {
+  writeFileSync(join(dir, '.connelio-state.json'), JSON.stringify(state, null, 2), { mode: 0o600 });
+}

package/src/hermes.mjs

@@ -0,0 +1,43 @@
+// Hermes 一键接入：配对拿到 token 后，用 Hermes 自己的 `hermes config set` 把 Telegram 通道指向 Connelio。
+// Hermes 走 python-telegram-bot，原生支持 platforms.telegram.extra.base_url —— 不需要给 Hermes 装任何插件。
+import { spawnSync } from 'node:child_process';
+
+export function hermesCli(profile) {
+  const bin = process.env.CONNELIO_HERMES_BIN || 'hermes';
+  const prefix = profile ? ['-p', profile] : [];
+  const run = (args) => spawnSync(bin, [...prefix, ...args], { encoding: 'utf8' });
+  return {
+    available() {
+      const r = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+      return !r.error && r.status === 0;
+    },
+    /** 这个 profile 是否已经接着一个 Telegram 机器人（接上 Connelio 会把它替换掉） */
+    existingTelegramToken() {
+      const r = run(['config', 'get', 'TELEGRAM_BOT_TOKEN']);
+      const value = (r.stdout || '').trim();
+      return r.status === 0 && value && !/^(none|null|not set|)$/i.test(value) ? value : '';
+    },
+    ensureProfile() {
+      if (!profile) return;
+      spawnSync(bin, ['profile', 'create', profile, '--clone'], { encoding: 'utf8' });   // 已存在会失败，无妨
+    },
+    set(key, value) {
+      const r = run(['config', 'set', key, String(value)]);
+      if (r.error || r.status !== 0) throw new Error(`hermes config set ${key} failed: ${(r.stderr || r.error?.message || '').trim()}`);
+    },
+    restart() {
+      const r = run(['gateway', 'restart']);
+      return !r.error && r.status === 0;
+    },
+  };
+}
+
+export function configureHermes({ hermes, server, token, ownerTelegramId }) {
+  const base = server.replace(/\/+$/, '');
+  hermes.set('platforms.telegram.enabled', 'true');
+  hermes.set('platforms.telegram.extra.base_url', `${base}/tg/bot`);
+  hermes.set('platforms.telegram.extra.base_file_url', `${base}/tg/file/bot`);
+  hermes.set('TELEGRAM_BOT_TOKEN', token);
+  // Hermes 默认谁都不放行：只放主人本人
+  if (ownerTelegramId) hermes.set('TELEGRAM_ALLOWED_USERS', ownerTelegramId);
+}

package/src/pair.mjs

@@ -0,0 +1,35 @@
+// 设备码配对：终端出二维码 + 8 位码 → 手机确认 → 一次性领 token。
+import QRCode from 'qrcode';
+import { hostname } from 'node:os';
+
+export async function pair({ server, kind, deviceName = prettyHost(), out = process.stdout, signal }) {
+  const base = server.replace(/\/+$/, '');
+  const started = await fetch(`${base}/api/agent-pair/start`, { method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ deviceName, kind }), signal });
+  if (started.status === 404) throw new Error('This Connelio server does not have agent pairing enabled yet.');
+  if (!started.ok) throw new Error(`Pairing failed to start (HTTP ${started.status}).`);
+  const pairing = await started.json();
+  const qr = await QRCode.toString(pairing.qr, { type: 'terminal', small: true, errorCorrectionLevel: 'M' });
+  out.write(`\n${qr}\n`);
+  out.write(`  Open Connelio on your phone → Chats → + → Connect an Agent\n`);
+  out.write(`  Scan the QR code above, or enter this code:  ${pairing.code}\n\n`);
+  out.write(`  在手机 Connelio 里：消息 → 右上 + → 接入 Agent，扫上面的码或输入配对码。\n\n`);
+  const deadline = Date.now() + pairing.expiresInSeconds * 1000;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error('Pairing cancelled.');
+    const response = await fetch(`${base}/api/agent-pair/poll`, { method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ pairingId: pairing.pairingId, pollSecret: pairing.pollSecret, timeout: 20 }), signal }).catch(() => null);
+    if (!response) { await sleep(2000); continue; }
+    const result = await response.json().catch(() => ({}));
+    if (result.status === 'approved') return result;
+    if (result.status === 'denied') throw new Error('Pairing was declined on the phone.');
+    if (result.status === 'expired' || response.status === 404) throw new Error('The pairing code expired. Run the command again.');
+    if (result.status === 'claimed') throw new Error('This pairing was already used.');
+  }
+  throw new Error('The pairing code expired. Run the command again.');
+}
+
+function prettyHost() {
+  return hostname().replace(/\.local$/, '').slice(0, 48) || 'Computer';
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/runner.mjs

@@ -0,0 +1,203 @@
+// 主循环：长轮询收消息 → 按会话排队（同一会话串行、不同会话并行）→ 交给适配器 → 进度卡 / 授权按钮 / 回复。
+//
+// 会话隔离（对外代理的底线）：每个会话一个独立目录和独立状态（对话历史 id、附件），适配器只拿到本会话的东西。
+// 访问控制：private 模式只认主人；public 模式谁都能用，但陌生人第一次来先告知"代理由谁运行、内容对方可见"。
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { readState, sessionDir, writeState } from './config.mjs';
+
+const MAX_CHUNK = 3800;
+const APPROVAL_TIMEOUT_MS = 10 * 60_000;
+const PROGRESS_THROTTLE_MS = 1500;
+
+export async function runAgent({ api, config, adapter, log = console.log, signal }) {
+  const me = await api.getMe();
+  const owner = config.owner;
+  const pendingApprovals = new Map();      // id → {resolve, conversationId, messageId, title}
+  const queues = new Map();                // conversationId → Promise chain
+  const told = new Set();                  // 已经提示过的 conversationId:accountId
+  let offset = 0;
+  let leaseWarned = false;
+
+  if (config.conversationId && !config.greeted) {
+    await api.sendMessage(config.conversationId, `✅ ${me.displayName} is online`).catch(() => undefined);
+    config.greeted = true;
+  }
+  log(`[connelio] ${me.displayName} (@${me.username}) is online — mode=${config.mode}, agent=${adapter.name}`);
+
+  while (!signal?.aborted) {
+    let batch;
+    try {
+      batch = await api.getUpdates({ offset, timeout: 25, signal });
+      leaseWarned = false;
+    } catch (error) {
+      if (signal?.aborted) break;
+      if (error.code === 'BOT_LEASE_HELD') {
+        if (!leaseWarned) log('[connelio] This agent is already running on another computer. Waiting…');
+        leaseWarned = true;
+        await sleep(10_000);
+      } else if (error.status === 401) {
+        log('[connelio] The token was revoked or the agent was disabled. Run `npx connelio connect` again.');
+        return;
+      } else {
+        log(`[connelio] connection problem (${error.message}), retrying…`);
+        await sleep(3000);
+      }
+      continue;
+    }
+    for (const item of batch.result ?? []) {
+      if (item.callbackQuery) { await onCallback(item.callbackQuery); continue; }
+      if (item.message) enqueue(item.message, item.chat);
+    }
+    if (batch.cursor?.nextOffset) offset = batch.cursor.nextOffset;
+  }
+
+  async function onCallback(tap) {
+    const match = /^ap:([0-9a-f-]{36}):(allow|always|deny)$/.exec(tap.data || '');
+    if (!match) { await api.answerCallback(tap.id); return; }
+    const pending = pendingApprovals.get(match[1]);
+    if (!pending) { await api.answerCallback(tap.id, 'Expired'); return; }
+    if (tap.from?.id !== owner.accountId) { await api.answerCallback(tap.id, 'Only the owner can approve this.'); return; }
+    pendingApprovals.delete(match[1]);
+    await api.answerCallback(tap.id, match[2] === 'deny' ? 'Denied' : 'Allowed');
+    const label = match[2] === 'deny' ? '✗ Denied' : match[2] === 'always' ? '✓ Allowed for this chat' : '✓ Allowed';
+    await api.editMessage(pending.messageId, { text: `${pending.title}\n${label}` }).catch(() => undefined);
+    await api.editButtons(pending.messageId, null).catch(() => undefined);
+    pending.resolve(match[2]);
+  }
+
+  function enqueue(message, chat) {
+    const key = chat.id;
+    const previous = queues.get(key) ?? Promise.resolve();
+    const next = previous.then(() => handle(message, chat)).catch((error) => log(`[connelio] ${error?.stack || error}`));
+    queues.set(key, next);
+    next.finally(() => { if (queues.get(key) === next) queues.delete(key); });
+  }
+
+  async function handle(message, chat) {
+    const sender = message.sender ?? {};
+    const isOwner = sender.id === owner.accountId;
+    const conversationId = chat.id;
+    let text = String(message.content ?? '');
+    if (chat.type !== 'direct') {
+      const addressed = text.includes(`@${me.username}`) || (message.mentionedAccountIds ?? []).includes(me.accountId)
+        || message.repliedTo?.senderId === me.accountId || text.startsWith('/');
+      if (!addressed) return;
+      text = text.replaceAll(`@${me.username}`, '').trim();
+    }
+    const toldKey = `${conversationId}:${sender.id}`;
+    if (config.mode === 'private' && !isOwner) {
+      if (!told.has(toldKey)) { told.add(toldKey); await api.sendMessage(conversationId, 'This agent only works for its owner.'); }
+      return;
+    }
+    if (config.mode === 'public' && !isOwner && !told.has(toldKey)) {
+      told.add(toldKey);
+      const ownerName = owner.username ? `@${owner.username}` : 'its owner';
+      await api.sendMessage(conversationId, `ℹ️ This agent is run by ${ownerName} on their own computer. Anything you send here is visible to them.`);
+    }
+
+    const dir = sessionDir(me.username, conversationId);
+    const attachments = [];
+    if (message.attachmentUrl) {
+      try {
+        const bytes = await api.download(message.attachmentUrl);
+        const inbox = join(dir, 'inbox');
+        mkdirSync(inbox, { recursive: true });
+        const name = `${Date.now()}-${basename(message.attachmentName || 'file').replace(/[^\w.\-]/g, '_')}`;
+        writeFileSync(join(inbox, name), bytes);
+        attachments.push(join(inbox, name));
+        if (text === '[Image]' || text === message.attachmentName) text = '';
+      } catch (error) { log(`[connelio] attachment download failed: ${error.message}`); }
+    }
+    if (!text && !attachments.length) return;
+
+    const progress = createProgress(conversationId);
+    const typing = setInterval(() => void api.typing(conversationId), 2000);
+    void api.typing(conversationId);
+    try {
+      const result = await adapter.run({
+        text, attachments, conversationId, chatType: chat.type, sender, isOwner, mode: config.mode,
+        dir,
+        // 只有主人在 private 模式下才进你指定的项目目录；其余一律关在本会话的隔间里
+        cwd: config.mode === 'private' && isOwner && config.dir ? config.dir : dir,
+        knowledge: config.knowledge ?? null,
+        state: () => readState(dir),
+        setState: (patch) => writeState(dir, { ...readState(dir), ...patch }),
+        progress,
+        askApproval: (title, detail) => askApproval(conversationId, title, detail),
+        log,
+      });
+      await progress.finish();
+      if (result?.text) await reply(conversationId, result.text);
+    } catch (error) {
+      await progress.finish('✗ Failed');
+      await reply(conversationId, `Sorry, something went wrong: ${error?.message || error}`);
+    } finally {
+      clearInterval(typing);
+    }
+  }
+
+  function createProgress(conversationId) {
+    let messageId = null, lines = [], last = 0, timer = null, steps = 0;
+    const flush = async () => {
+      timer = null; last = Date.now();
+      const body = `⏳ Working…\n${lines.slice(-6).join('\n')}`.slice(0, MAX_CHUNK);
+      if (!messageId) messageId = (await api.sendMessage(conversationId, body).catch(() => null))?.id ?? null;
+      else await api.editMessage(messageId, { text: body }).catch(() => undefined);
+    };
+    return {
+      step(line) {
+        steps += 1;
+        lines.push(`• ${String(line).slice(0, 160)}`);
+        if (timer) return;
+        const wait = Math.max(0, PROGRESS_THROTTLE_MS - (Date.now() - last));
+        timer = setTimeout(() => void flush(), wait);
+      },
+      async finish(label) {
+        if (timer) { clearTimeout(timer); timer = null; }
+        if (!messageId) return;
+        await api.editMessage(messageId, { text: `${label ?? `✓ Done · ${steps} step${steps === 1 ? '' : 's'}`}\n${lines.slice(-6).join('\n')}`.slice(0, MAX_CHUNK) }).catch(() => undefined);
+      },
+    };
+  }
+
+  async function askApproval(conversationId, title, detail) {
+    const id = randomUUID();
+    const body = `🔐 ${title}${detail ? `\n${String(detail).slice(0, 600)}` : ''}`;
+    const sent = await api.sendMessage(conversationId, body, { inline_keyboard: [[
+      { text: 'Allow', callback_data: `ap:${id}:allow`, style: 'primary' },
+      { text: 'Always in this chat', callback_data: `ap:${id}:always` },
+      { text: 'Deny', callback_data: `ap:${id}:deny`, style: 'danger' },
+    ]] });
+    return new Promise((resolve) => {
+      pendingApprovals.set(id, { resolve, conversationId, messageId: sent.id, title: body });
+      setTimeout(() => {
+        if (!pendingApprovals.has(id)) return;
+        pendingApprovals.delete(id);
+        void api.editButtons(sent.id, null).catch(() => undefined);
+        resolve('deny');
+      }, APPROVAL_TIMEOUT_MS).unref?.();
+    });
+  }
+
+  async function reply(conversationId, text) {
+    for (const chunk of split(String(text))) await api.sendMessage(conversationId, chunk);
+  }
+}
+
+export function split(text) {
+  if (text.length <= MAX_CHUNK) return [text];
+  const out = [];
+  let rest = text;
+  while (rest.length > MAX_CHUNK) {
+    let cut = rest.lastIndexOf('\n', MAX_CHUNK);
+    if (cut < MAX_CHUNK * 0.5) cut = MAX_CHUNK;
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/, '');
+  }
+  if (rest) out.push(rest);
+  return out;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));