connelio 0.0.0-stage → 0.1.2

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,94 @@
-# 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
+```
+
+That's the whole thing — it never asks you to choose between commands. If the Hermes on this computer already talks to a Telegram bot, Connelio gets its own Hermes profile (`connelio`) and leaves that bot alone; if a `connelio` profile is already there, it is reused. Only `--replace` swaps the bot your current profile uses. To put Connelio on a specific profile instead: `--hermes-profile <name>`.
+
+Each step prints as it happens — checking Hermes, preparing the config, waiting for your phone, connected, restarting Hermes — and a failed step says what to do next. The QR code is drawn large (two characters per module, quiet zone around it, and the pairing code on its own line below), and falls back to the compact version only when the terminal is too narrow for it.
+
+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 (`hermes gateway ensure` when it is not running yet).
+
+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,198 @@
+#!/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, ISOLATED_PROFILE, isConnelioBase } from '../src/hermes.mjs';
+import { createProgress } from '../src/progress.mjs';
+import { copy as copyFor, detectLang } from '../src/i18n.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 choosing one for you
+  --replace               with --hermes: replace the Telegram bot this Hermes profile already uses
+
+With --hermes, if the Hermes on this computer already talks to a Telegram bot, Connelio
+gets its own Hermes profile (${ISOLATED_PROFILE}) and leaves that bot alone. No questions asked.
+`;
+
+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 };
+}
+
+const flagOn = (value) => value === true || value === 'true' || value === '1';
+const firstLine = (message) => String(message || '').split('\n').map((l) => l.trim()).filter(Boolean)[0] || '';
+
+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);
+}
+
+/** connect --hermes：一步不停，不再让用户在两行命令里选。 */
+async function connectHermes({ server, flags, out = process.stdout }) {
+  const text = copyFor(detectLang());
+  const progress = createProgress(out);
+  const replace = flagOn(flags.replace);
+  const explicit = typeof flags['hermes-profile'] === 'string' ? flags['hermes-profile'] : '';
+  const deviceName = typeof flags.name === 'string' ? flags.name : undefined;
+
+  // 1 检查 Hermes
+  if (!hermesCli('').available()) {
+    progress.fail(text.steps.check, text.errors.noHermes.why, text.errors.noHermes.next);
+    return 1;
+  }
+  progress.ok(text.steps.check);
+
+  // 2 建配置：已有别的 Telegram 机器人就自动开独立 profile（原来的不受影响），只有 --replace 才替换
+  let profile = explicit;
+  let notice = '';
+  if (!explicit && !replace) {
+    const state = hermesCli('').telegramState();
+    if (state.token && !isConnelioBase(state.baseUrl, server)) profile = ISOLATED_PROFILE;
+    else if (state.token) notice = text.alreadyConnelio;
+  }
+  if (explicit && !replace) {
+    const state = hermesCli(explicit).telegramState();
+    if (state.token && !isConnelioBase(state.baseUrl, server)) {
+      progress.fail(text.steps.prepare, text.errors.profileHasBot.why(explicit), text.errors.profileHasBot.next);
+      return 1;
+    }
+  }
+  const hermes = hermesCli(profile);
+  let prepared;
+  try {
+    prepared = hermes.ensureProfile();
+  } catch (error) {
+    progress.fail(text.steps.prepare, text.errors.profileFailed.why, text.errors.profileFailed.next);
+    progress.note(firstLine(error.message));
+    return 1;
+  }
+  progress.ok(text.steps.prepare);
+  if (profile === ISOLATED_PROFILE && !explicit) progress.note(prepared.existed ? text.reuseProfile : text.createProfile);
+  else if (replace) progress.note(text.keepActive);
+  if (notice) progress.note(notice);
+
+  // 3 二维码 + 等手机扫码
+  progress.waiting(text.steps.scan);
+  let result;
+  try {
+    result = await pair({ server, kind: 'hermes', deviceName, out });
+  } catch (error) {
+    const known = text.errors[error.code];
+    progress.fail(text.steps.scan, known?.why || text.errors.network.why, known?.next || text.errors.network.next);
+    if (!known && error.message) progress.note(firstLine(error.message));
+    return 1;
+  }
+
+  // 4 写配置 = 已连接
+  try {
+    configureHermes({ hermes, server, token: result.token, ownerTelegramId: result.owner?.telegramId });
+  } catch (error) {
+    progress.fail(text.steps.connected, text.errors.configWrite.why, text.errors.configWrite.next);
+    progress.note(firstLine(error.message));
+    return 1;
+  }
+  const bot = result.bot ?? {};
+  progress.ok(`${text.steps.connected}${bot.displayName ? ` — ${bot.displayName}${bot.username ? ` (@${bot.username})` : ''}` : ''}`);
+
+  // 5 重启 Hermes
+  const startCommand = `hermes${profile ? ` -p ${profile}` : ''} gateway run`;
+  progress.begin(text.steps.restart);
+  if (hermes.restart()) progress.ok(text.steps.restart);
+  else progress.warn(text.steps.restart, `${text.manualStart} ${startCommand}`);
+
+  progress.blank();
+  out.write(`  ${text.done}\n`);
+  return 0;
+}
+
+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) {
+    process.exitCode = await connectHermes({ server, flags });
+    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.2",
+  "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,89 @@
+// Hermes 一键接入：配对拿到 token 后，用 Hermes 自己的 `hermes config set` 把 Telegram 通道指向 Connelio。
+// Hermes 走 python-telegram-bot，原生支持 platforms.telegram.extra.base_url —— 不需要给 Hermes 装任何插件。
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** 独立 profile 名字：已有 Telegram 机器人时，Connelio 用它自己的配置，互不影响。 */
+export const ISOLATED_PROFILE = 'connelio';
+
+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', env: { ...process.env, NO_COLOR: '1' } });
+  const cli = {
+    profile,
+    available() {
+      const r = spawnSync(bin, ['--version'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      return !r.error && r.status === 0;
+    },
+    /** 这个 profile 名是否已经存在（`hermes profile list` 第一列） */
+    profileExists() {
+      if (!profile) return true;
+      const r = spawnSync(bin, ['profile', 'list'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      if (r.error || r.status !== 0) return existsSync(join(homedir(), '.hermes', 'profiles', profile));
+      return r.stdout.split('\n')
+        .map((line) => line.replace(/[─━│]/g, ' ').trim().split(/\s+/)[0] || '')
+        .map((name) => name.replace(/^[^\w.-]+/, ''))
+        .includes(profile);
+    },
+    /** 读一个配置项；没设置返回空串（Hermes 会打“Config key not set”并退出 1） */
+    get(key) {
+      const r = run(['config', 'get', key]);
+      if (r.error || r.status !== 0) return '';
+      const value = (r.stdout || '').trim();
+      return /^config key not set/i.test(value) ? '' : value;
+    },
+    /** 当前 profile 的 Telegram 状况：是否已有机器人、指向哪里 */
+    telegramState() {
+      const token = cli.get('TELEGRAM_BOT_TOKEN');
+      const baseUrl = cli.get('platforms.telegram.extra.base_url');
+      return { token, baseUrl, enabled: /^(true|1|yes)$/i.test(cli.get('platforms.telegram.enabled')) };
+    },
+    /** 建 profile（--clone：不带原来的机器人 token）；已存在就复用 */
+    ensureProfile() {
+      if (!profile) return { existed: true, created: false };
+      if (cli.profileExists()) return { existed: true, created: false };
+      const r = spawnSync(bin, ['profile', 'create', profile, '--clone'], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      if (r.error || r.status !== 0) throw new Error((r.stderr || r.error?.message || `hermes profile create exited ${r.status}`).trim());
+      return { existed: false, created: true };
+    },
+    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()}`);
+    },
+    /** 网关现在是否在跑（`gateway status` 没跑时也退出 0，只能看文字） */
+    gatewayRunning() {
+      const r = run(['gateway', 'status']);
+      return !r.error && r.status === 0 && !/not running/i.test(`${r.stdout || ''}${r.stderr || ''}`);
+    },
+    /** 让新配置生效：在跑就重启；没跑就拉起来（ensure 起本地运行时，不装服务）。
+     *  真机上这两条都要几十秒，给足时间但不许无限等。 */
+    restart({ timeout = 150_000 } = {}) {
+      const r = spawnSync(bin, [...prefix, 'gateway', cli.gatewayRunning() ? 'restart' : 'ensure'], { encoding: 'utf8', timeout, env: { ...process.env, NO_COLOR: '1' } });
+      return !r.error && r.status === 0;
+    },
+  };
+  return cli;
+}
+
+/** 同一台 Connelio 服务器的配对地址（已经接着 Connelio 时不必再开独立 profile） */
+export function isConnelioBase(baseUrl, server) {
+  if (!baseUrl) return false;
+  try {
+    const configured = new URL(baseUrl);
+    const target = new URL(server);
+    return configured.origin === target.origin && /\/tg\/bot\/?$/.test(configured.pathname);
+  } catch { return false; }
+}
+
+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/i18n.mjs

@@ -0,0 +1,68 @@
+// 命令行文字：跟系统语言走（中文系统出中文，其余出英文）。只影响终端里的提示，不影响协议。
+export function detectLang(env = process.env, intlLocale) {
+  const raw = String(env.CONNELIO_LANG || env.LC_ALL || env.LC_MESSAGES || env.LANG || '').toLowerCase();
+  const tag = raw || String(intlLocale || (typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().locale : '') || 'en').toLowerCase();
+  if (tag.startsWith('zh')) return 'zh';
+  return 'en';
+}
+
+const COPY = {
+  zh: {
+    steps: { check: '检查 Hermes', prepare: '建配置', scan: '等手机扫码…', connected: '已连接', restart: '重启 Hermes' },
+    createProfile: '已为 Connelio 单独建了一个 Hermes 配置，原来的 Telegram 不受影响。',
+    reuseProfile: '这台电脑上已有 connelio 配置，接着用它，原来的 Telegram 不受影响。',
+    keepActive: '用的就是当前这个 Hermes 配置（--replace）。',
+    alreadyConnelio: '这个 Hermes 已经接着 Connelio，这次会换成新的配对。',
+    scanHint: '手机上打开 Connelio：消息 → 右上 + → 接入 Agent，扫上面的码。',
+    codeLabel: '配对码',
+    manualStart: 'Hermes 没在后台运行，手动启动一次：',
+    done: '好了，在手机 Connelio 里给它发条消息试试。',
+    errors: {
+      noHermes: { why: '这台电脑上没找到 Hermes。', next: '先安装 Hermes（https://hermes-agent.nousresearch.com），装好再跑一次。' },
+      profileHasBot: {
+        why: (name) => `配置 ${name} 已经接着一个 Telegram 机器人。`,
+        next: '想保留它：去掉 --hermes-profile，让 Connelio 自己建配置；确实要替换：加 --replace。',
+      },
+      profileFailed: { why: '新建 Hermes 配置失败。', next: '跑 hermes profile create connelio --clone 看具体报错，修好再重试。' },
+      'start-failed': { why: '连不上 Connelio 服务器。', next: '检查网络；换服务器用 --server https://…，然后重试。' },
+      declined: { why: '手机上取消了配对。', next: '想接的话再跑一次：npx connelio connect --hermes' },
+      expired: { why: '配对码过期了。', next: '再跑一次，重新出码。' },
+      claimed: { why: '这个配对码已经被用过了。', next: '再跑一次，重新出码。' },
+      cancelled: { why: '已取消。', next: '重新跑一次即可。' },
+      notSupported: { why: '这台服务器还没开配对功能。', next: '升级 Connelio 服务端，或用 --server 指向已开通的服务器。' },
+      network: { why: '和服务器通信中断了。', next: '网络恢复后再跑一次。' },
+      configWrite: { why: '写入 Hermes 配置失败。', next: '看上面那行报错；修好后重跑本命令。' },
+    },
+    retry: '再跑一次：npx connelio connect --hermes',
+  },
+  en: {
+    steps: { check: 'Checking Hermes', prepare: 'Preparing config', scan: 'Waiting for your phone…', connected: 'Connected', restart: 'Restarting Hermes' },
+    createProfile: 'Connelio got its own Hermes profile. Your existing Telegram bot is untouched.',
+    reuseProfile: 'Reusing the connelio profile on this computer. Your existing Telegram bot is untouched.',
+    keepActive: 'Using this Hermes profile (--replace).',
+    alreadyConnelio: 'This Hermes is already connected to Connelio — this run replaces the pairing.',
+    scanHint: 'On your phone open Connelio: Chats → + → Connect an Agent, then scan the code above.',
+    codeLabel: 'Pairing code',
+    manualStart: 'Hermes is not running in the background. Start it once:',
+    done: 'Done. Send it a message from Connelio on your phone.',
+    errors: {
+      noHermes: { why: 'Hermes was not found on this computer.', next: 'Install Hermes (https://hermes-agent.nousresearch.com), then run this again.' },
+      profileHasBot: {
+        why: (name) => `The ${name} profile already talks to a Telegram bot.`,
+        next: 'To keep it, drop --hermes-profile and let Connelio make its own profile; to replace it, add --replace.',
+      },
+      profileFailed: { why: 'Could not create the Hermes profile.', next: 'Run hermes profile create connelio --clone to see the error, fix it, then retry.' },
+      'start-failed': { why: 'Could not reach the Connelio server.', next: 'Check your network; use --server https://… for another server, then retry.' },
+      declined: { why: 'Pairing was declined on the phone.', next: 'Run it again when you want to connect: npx connelio connect --hermes' },
+      expired: { why: 'The pairing code expired.', next: 'Run it again for a fresh code.' },
+      claimed: { why: 'That pairing code was already used.', next: 'Run it again for a fresh code.' },
+      cancelled: { why: 'Cancelled.', next: 'Just run it again.' },
+      notSupported: { why: 'This server does not have pairing enabled.', next: 'Upgrade the Connelio server, or point --server at one that has it.' },
+      network: { why: 'Lost contact with the server.', next: 'Run it again when the network is back.' },
+      configWrite: { why: 'Writing the Hermes settings failed.', next: 'Read the error line above, fix it, then run this again.' },
+    },
+    retry: 'Run it again: npx connelio connect --hermes',
+  },
+};
+
+export const copy = (lang) => COPY[lang] || COPY.en;

package/src/pair.mjs

@@ -0,0 +1,63 @@
+// 设备码配对：终端出二维码 + 8 位码 → 手机确认 → 一次性领 token。
+import { hostname } from 'node:os';
+import { fitsWide, renderQr } from './qr.mjs';
+import { copy as copyFor, detectLang } from './i18n.mjs';
+
+export class PairError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.code = code;
+  }
+}
+
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+const bold = (text) => `${BOLD}${text}${RESET}`;
+
+export async function pair({ server, kind, deviceName = prettyHost(), out = process.stdout, signal, lang = detectLang(), columns = out.columns, tty = out.isTTY }) {
+  const text = copyFor(lang);
+  const base = server.replace(/\/+$/, '');
+  let started;
+  try {
+    started = await fetch(`${base}/api/agent-pair/start`, { method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ deviceName, kind }), signal });
+  } catch (error) {
+    if (error?.name === 'AbortError') throw new PairError('cancelled');
+    throw new PairError('start-failed', error?.message);
+  }
+  if (started.status === 404) throw new PairError('notSupported');
+  if (!started.ok) throw new PairError('start-failed', `HTTP ${started.status}`);
+  const pairing = await started.json();
+
+  // 大码优先：每格两字符，放不进终端才退小码
+  const big = fitsWide(pairing.qr, columns);
+  out.write(`\n${renderQr(pairing.qr, { small: !big, indent: 2 })}\n\n`);
+  out.write(`  ${text.scanHint}\n\n`);
+  const strong = tty ? bold : (value) => value;
+  out.write(`  ${strong(text.codeLabel)}  ${strong(pairing.code)}\n\n`);
+
+  const deadline = Date.now() + pairing.expiresInSeconds * 1000;
+  let dropped = 0;   // 连续连不上就别死等：网络断了要立刻说人话
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new PairError('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) {
+      if (++dropped >= 3) throw new PairError('network');
+      await sleep(2000);
+      continue;
+    }
+    dropped = 0;
+    const result = await response.json().catch(() => ({}));
+    if (result.status === 'approved') return result;
+    if (result.status === 'denied') throw new PairError('declined');
+    if (result.status === 'expired' || response.status === 404) throw new PairError('expired');
+    if (result.status === 'claimed') throw new PairError('claimed');
+  }
+  throw new PairError('expired');
+}
+
+function prettyHost() {
+  return hostname().replace(/\.local$/, '').slice(0, 48) || 'Computer';
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/progress.mjs

@@ -0,0 +1,52 @@
+// 每一步一行：终端里先显示「… 这一步」，做完原地变成「✓ 这一步」；
+// 输出被重定向到文件时只留结果行，日志照样看得懂。
+export function createProgress(out = process.stdout, { tty = Boolean(out.isTTY) } = {}) {
+  let open = false;
+  const close = () => { if (open) { if (tty) out.write('\r\x1b[2K'); open = false; } };
+  return {
+    starts: () => tty,
+    /** 开始一步（可打印「…」），fn 返回后收尾成 ✓；fn 抛错就只写 ✗ 交给调用方 */
+    async step(label, fn) {
+      if (tty) { close(); out.write(`  … ${label}`); open = true; }
+      try {
+        const value = await fn();
+        close();
+        out.write(`  ✓ ${label}\n`);
+        return value;
+      } catch (error) {
+        close();
+        throw error;
+      }
+    },
+    /** 耗时又不确定多久的一步：先把「…」打出来（重定向到日志也打），做完再收尾 */
+    begin(label) {
+      close();
+      out.write(`  … ${label}\n`);
+    },
+    /** 长时间等待（等手机扫码）：这行要一直留着 */
+    waiting(label) {
+      close();
+      if (tty) { out.write(`  … ${label}`); open = true; } else out.write(`  … ${label}\n`);
+    },
+    ok(label) {
+      close();
+      out.write(`  ✓ ${label}\n`);
+    },
+    fail(label, why, next) {
+      close();
+      out.write(`  ✗ ${label}\n`);
+      if (why) out.write(`    ${why}\n`);
+      if (next) out.write(`    → ${next}\n`);
+    },
+    warn(label, next) {
+      close();
+      out.write(`  ! ${label}\n`);
+      if (next) out.write(`    → ${next}\n`);
+    },
+    note(line) {
+      close();
+      if (line) out.write(`    ${line}\n`);
+    },
+    blank() { close(); out.write('\n'); },
+  };
+}

package/src/qr.mjs

@@ -0,0 +1,46 @@
+// 终端二维码：每格两字符（大码，手机好扫），四周留白两格；终端太窄才退回半高小码。
+// 自己按矩阵画，不依赖 ANSI 背景色 —— 复制粘贴到别处也不会变成乱码。
+import QRCode from 'qrcode';
+
+export const MARGIN = 2;
+
+function matrixOf(text, errorCorrectionLevel) {
+  const { modules } = QRCode.create(text, { errorCorrectionLevel });
+  return { size: modules.size, dark: (x, y) => x >= 0 && y >= 0 && x < modules.size && y < modules.size && Boolean(modules.get(x, y)) };
+}
+
+/** 大码宽度（含留白），用于判断终端放不放得下 */
+export function wideWidth(text, { margin = MARGIN, errorCorrectionLevel = 'M' } = {}) {
+  return (matrixOf(text, errorCorrectionLevel).size + margin * 2) * 2;
+}
+
+/** 窄终端用：一格一字符、两行并一行（半块字符），宽度减半 */
+export function fitsWide(text, columns, options) {
+  return !columns || wideWidth(text, options) <= columns;
+}
+
+export function renderQr(text, { small = false, margin = MARGIN, errorCorrectionLevel = 'M', indent = 0 } = {}) {
+  const { size, dark } = matrixOf(text, errorCorrectionLevel);
+  const pad = ' '.repeat(indent);
+  const lines = [];
+  const from = -margin;
+  const to = size + margin;
+  if (!small) {
+    for (let y = from; y < to; y++) {
+      let line = '';
+      for (let x = from; x < to; x++) line += dark(x, y) ? '██' : '  ';
+      lines.push(pad + line);
+    }
+    return lines.join('\n');
+  }
+  for (let y = from; y < to; y += 2) {
+    let line = '';
+    for (let x = from; x < to; x++) {
+      const top = dark(x, y);
+      const bottom = dark(x, y + 1);
+      line += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+    }
+    lines.push(pad + line);
+  }
+  return lines.join('\n');
+}

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));