controlmesh 0.17.0__tar.gz

controlmesh-0.17.0/.gitignore

@@ -0,0 +1,87 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Type checking & linting
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# IDE & editors
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+*.swn
+*~
+.project
+.settings/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Environment & secrets
+.env
+.env.*
+
+# Runtime
+*.pid
+*.log
+*.sock
+
+# Local harness/controller scratch
+/evidence.yaml
+/proposed_*.md
+/plans/tasks/*
+!/plans/tasks/README.md
+!/plans/tasks/_template/
+!/plans/tasks/_template/**
+
+# Local agent/development artifacts (keep out of public releases)
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+TASKMEMORY.md
+**/TASKMEMORY.md
+**/findings.md
+**/progress.md
+**/result.md
+**/task_plan.md
+
+# Local release/certification runtime outputs
+/task_artifacts/**/api_runtime_home/
+/task_artifacts/**/fresh_home*/
+/task_artifacts/**/live_drill/config.before.json
+/task_artifacts/**/live_drill/state.env
+
+# Local uv workspace lock generated during ad-hoc verification
+/uv.lock
+
+# Personal / dev-only (not part of the project)
+start_bot.sh
+python_best_practice.md
+/run.py

controlmesh-0.17.0/Dockerfile.sandbox

@@ -0,0 +1,48 @@
+# Dockerfile.sandbox -- lightweight sandbox for controlmesh CLI execution.
+# Based on Node 22 (Debian bookworm) with Python 3, Claude Code CLI,
+# and Codex CLI pre-installed.  The container runs "sleep infinity" so
+# controlmesh can `docker exec` into it on demand.
+
+FROM node:22-bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    LANG=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8 \
+    PIP_BREAK_SYSTEM_PACKAGES=1
+
+# System packages: Python, build tools, Git, locale support
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       python3 python3-pip python3-venv python3-dev \
+       build-essential git curl ca-certificates sudo locales \
+    && sed -i '/en_US.UTF-8/s/^# //' /etc/locale.gen && locale-gen \
+    && rm -rf /var/lib/apt/lists/*
+
+# Chrome/Chromium runtime dependencies for browser-based skills
+# (e.g. patchright, playwright). Only shared libraries -- no browser binary.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       libasound2 libatk-bridge2.0-0 libatk1.0-0 libcairo2 libcups2 \
+       libdbus-1-3 libdrm2 libexpat1 libgbm1 libglib2.0-0 libnspr4 \
+       libnss3 libpango-1.0-0 libx11-6 libx11-xcb1 libxcb1 \
+       libxcomposite1 libxdamage1 libxext6 libxfixes3 libxkbcommon0 \
+       libxrandr2 libxshmfence1 \
+       fonts-liberation fonts-noto-color-emoji \
+    && rm -rf /var/lib/apt/lists/*
+
+# Allow pip installs without the "externally managed" guard
+RUN rm -f /usr/lib/python*/EXTERNALLY-MANAGED
+
+# Install Claude Code CLI and Codex CLI
+RUN npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli
+
+# Prepare a writable data directory
+RUN mkdir -p /data && chown node:node /data
+
+# Let the `node` user run sudo without a password (useful for apt inside sandbox)
+RUN echo "node ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/node
+
+USER node
+WORKDIR /workspace
+
+CMD ["sleep", "infinity"]

controlmesh-0.17.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 PleasePrompto
+
+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.

controlmesh-0.17.0/PKG-INFO

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: controlmesh
+Version: 0.17.0
+Summary: ControlMesh brings official coding CLIs into Telegram, Matrix, and Feishu with persistent workspaces, long-running jobs, and production-friendly bot operations.
+Project-URL: Homepage, https://github.com/muqiao215/ControlMesh
+Project-URL: Repository, https://github.com/muqiao215/ControlMesh
+Project-URL: Documentation, https://github.com/muqiao215/ControlMesh
+Project-URL: Issues, https://github.com/muqiao215/ControlMesh/issues
+Project-URL: Changelog, https://github.com/muqiao215/ControlMesh/releases
+Author: muqiao215
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,automation,bot,claude,cli,codex,controlmesh,streaming,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiogram<4.0.0,>=3.24.0
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: cronsim>=2.7
+Requires-Dist: filetype>=1.2.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: requests>=2.32.0
+Requires-Dist: rich>=14.3.2
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: api
+Requires-Dist: pynacl>=1.6.2; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: matrix-nio>=0.25.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pynacl>=1.6.2; extra == 'dev'
+Requires-Dist: pytest-aiohttp>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Requires-Dist: time-machine>=3.2.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: mypy>=1.19.1; extra == 'lint'
+Requires-Dist: ruff>=0.15.0; extra == 'lint'
+Provides-Extra: matrix
+Requires-Dist: matrix-nio>=0.25.0; extra == 'matrix'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents; extra == 'openai-agents'
+Provides-Extra: test
+Requires-Dist: pytest-aiohttp>=1.1.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
+Requires-Dist: pytest>=9.0.2; extra == 'test'
+Requires-Dist: time-machine>=3.2.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ControlMesh
+
+中文 | [English](#english)
+
+ControlMesh is a chat-native task runtime for official coding CLIs, with a
+Feishu-native product path and first-class Telegram and WeChat entrypoints.
+
+It turns Claude, Codex, Gemini, and other local command-line agents into a
+long-running work bot that can run background tasks, ask the parent chat for
+missing input, resume the worker, and return results through the same chat.
+Feishu native is the runtime-first product path; Telegram and WeChat/Weixin are
+also existing important entrypoints. Matrix, sub-agents, cron, webhooks, and API
+remain secondary compatibility lanes.
+
+![ControlMesh chat agent overview](docs/assets/controlmesh-feishu-runtime.svg)
+
+## 中文
+
+### 一句话
+
+ControlMesh 是一个开源的 chat-native task runtime：把 Claude、Codex、
+Gemini 等官方编码 CLI 接进飞书、Telegram 和微信，让它们像长期在线的任务
+机器人一样执行工作。
+
+它不是一次性的聊天壳。主线是飞书里的后台任务闭环：创建任务、任务后台执行、
+任务缺信息时通过 `ask_parent` 回问飞书、父会话恢复任务、结果回到同一聊天上下文。
+Telegram 和微信/WeChat 是项目已有的重要入口；Matrix 保留为次级兼容 transport。
+
+### 适合谁
+
+- 想把 Claude、Codex、Gemini 变成飞书、Telegram 或微信里的长期任务机器人。
+- 需要任务超过 30 秒时自动转后台，不阻塞聊天的人。
+- 需要 worker 缺信息时能在聊天里优雅回问并 resume 的团队。
+- 想把机器人部署到 VPS、NAS 或树莓派，做 24/7 工作入口的开发者。
+
+### 产品能力
+
+| 能力 | 说明 |
+|---|---|
+| Feishu Native Runtime | 内置 `feishu-auth-kit` 插件，提供扫码创建机器人、CardKit 单卡、权限引导、原生 OAPI 工具 |
+| 后台任务闭环 | `/tasks/create`、`ask_parent`、`resume`、`list` 构成可演示任务 runtime |
+| 官方 CLI worker | 复用 Claude、Codex、Gemini 等官方命令行工具执行任务 |
+| 持久工作区 | 会话、任务记忆、文件、输出和运行状态保存在本机 |
+| 文件交付 | 文本、图片、音频、文档等输出可发回聊天入口 |
+| 多入口触达 | Feishu 是 native/runtime-first 主线；Telegram 和微信/WeChat 是已有重要入口 |
+| 运维友好 | `tasks doctor`、Feishu doctor、systemd、restart、配置校验 |
+| 兼容入口 | Matrix、API、sub-agent、cron、webhook 仍可用，但不是首页主线 |
+
+### Feishu 体验
+
+ControlMesh 当前公开主线是 Feishu Native 模式。
+
+最小闭环：
+
+- `controlmesh feishu native bootstrap` 进入友好的飞书原生启动入口。
+- 内置 [`feishu-auth-kit`](https://github.com/muqiao215/feishu-auth-kit) 作为 Feishu native plugin，完成扫码创建、凭证写回、权限引导、消息上下文、CardKit 和 retry contract。
+- `feishu-auth-kit` 的公开仓库是上游元能力仓库；ControlMesh 发布包必须包含这套插件，外部 CLI 只作为开发覆盖或故障 fallback。
+- 当 Feishu native 使用 Codex provider 时，agent turn 主路径直接消费内置 plugin 的 `CodexCliRunner`、`AgentEvent` 和 `SingleCardRun`，再由 ControlMesh 负责飞书发送与卡片更新。
+- Feishu 卡片展示任务状态、工具步骤和最终结果。
+- 长任务通过 task runtime 后台执行，缺信息时走 `/tasks/ask_parent`，父会话再 `/tasks/resume`。
+- `/feishu_auth_all` 进行当前 MVP 工具所需权限的批量引导。
+- 已接入第一批只读原生工具：联系人搜索、用户读取、群消息读取、Drive 文件列表。
+
+### Telegram 与微信入口
+
+Feishu 是当前 native/runtime-first 主线，但 ControlMesh 不是只服务飞书：
+
+- Telegram：成熟的 token-based 入口，适合个人 DM、群组、长期在线任务机器人和文件交付。
+- 微信/WeChat：已有 Weixin iLink 入口，支持扫码登录、长轮询收消息，并在首条微信消息后建立回复上下文。
+- Matrix：保留为 secondary/compatibility transport，适合已经使用 Matrix/Element 的团队。
+
+Bridge 模式、Matrix、sub-agent、cron、webhook 和 API 仍是兼容能力；公开产品叙事以
+Feishu native + Telegram + 微信入口为主。
+
+### Runtime primitives
+
+任务闭环的稳定 runtime primitives：
+
+- `/tasks/create`
+- `/tasks/resume`
+- `/tasks/ask_parent`
+- `/tasks/list`
+- `/interagent/send`
+
+### 快速开始
+
+```bash
+pipx install controlmesh
+controlmesh
+```
+
+如果你想直接跟踪 GitHub 最新 `main`，不用等下一次 PyPI 发布：
+
+```bash
+pipx install "git+https://github.com/muqiao215/ControlMesh.git@main"
+controlmesh
+```
+
+从源码运行：
+
+```bash
+git clone https://github.com/muqiao215/ControlMesh.git
+cd ControlMesh
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[matrix,api]"
+controlmesh
+```
+
+首次启动会引导你完成 CLI 检查、聊天入口配置、时区设置和可选服务安装。
+
+### Feishu 从零配置
+
+Native 模式：
+
+```bash
+controlmesh feishu native bootstrap
+controlmesh auth feishu setup
+controlmesh auth feishu register-begin
+controlmesh auth feishu register-poll --device-code "<device_code>" --interval 5 --expires-in 600
+controlmesh auth feishu doctor
+controlmesh auth feishu probe
+```
+
+任务 runtime：
+
+```bash
+controlmesh tasks doctor
+controlmesh tasks list
+```
+
+### 常用命令
+
+```bash
+controlmesh status
+controlmesh restart
+controlmesh service install
+controlmesh api enable
+```
+
+### 文档
+
+- 安装：[`docs/installation.md`](docs/installation.md)
+- Feishu 设置：[`docs/feishu-setup.md`](docs/feishu-setup.md)
+- Telegram 设置：[`docs/telegram-setup.md`](docs/telegram-setup.md)
+- 微信/WeChat 设置：[`docs/weixin-setup.md`](docs/weixin-setup.md)
+- Case-pack contract：[`docs/case-pack/README.md`](docs/case-pack/README.md)
+- 文档总览：[`docs/README.md`](docs/README.md)
+- 配置示例：[`config.example.json`](config.example.json)
+
+### 许可证
+
+MIT License. See [`LICENSE`](LICENSE).
+
+---
+
+## English
+
+ControlMesh is an open-source chat-native task runtime for command-line coding
+agents.
+
+It turns official CLIs such as Claude, Codex, and Gemini into long-running chat
+bots that can spawn background tasks, ask the parent chat for missing context,
+resume the worker, and return results through the same conversation. Feishu
+native is the runtime-first product path; Telegram and WeChat/Weixin are also
+existing important entrypoints. Matrix remains a secondary compatibility
+transport.
+
+### Who It Is For
+
+- Developers who want Claude, Codex, or Gemini as long-running Feishu,
+  Telegram, or WeChat workers.
+- Teams that need a task loop: create, ask-parent, resume, return.
+- Builders who need agents to work with files and commands, not just produce chat text.
+- Operators who want an always-on chat task entrypoint on a VPS, NAS, or Raspberry Pi.
+
+### Features
+
+| Feature | Description |
+|---|---|
+| Feishu Native Runtime | Bundled `feishu-auth-kit` plugin for scan-created bots, CardKit cards, permission onboarding, and native OAPI tools |
+| Background task loop | `/tasks/create`, `ask_parent`, `resume`, and `list` form the runtime loop |
+| Official CLI workers | Run Claude, Codex, Gemini, and other local CLI agents |
+| Persistent workspace | Keep sessions, task memory, files, outputs, and runtime state on your machine |
+| File delivery | Return text, images, audio, documents, and generated artifacts to the chat entrypoint |
+| Multi-entrypoint access | Feishu is native/runtime-first; Telegram and WeChat/Weixin are existing important entrypoints |
+| Operations | `tasks doctor`, Feishu doctor, systemd service, restart, config validation |
+| Compatibility lanes | Matrix, API, sub-agents, cron, and webhooks remain available as secondary lanes |
+
+### Feishu Modes
+
+**Native mode** is the primary product path.
+
+- `controlmesh feishu native bootstrap` is the product-friendly entrypoint.
+- Bundles [`feishu-auth-kit`](https://github.com/muqiao215/feishu-auth-kit)
+  as the Feishu native plugin for scan-to-create onboarding, credential
+  write-back, permission flows, message context, CardKit, and retry contracts.
+- The standalone `feishu-auth-kit` repo is the upstream reusable capability
+  source. ControlMesh includes a vendored plugin copy; external CLI resolution
+  is a development override or fallback, not the product dependency.
+- Shows status, tool steps, and final output in a single Feishu card.
+- Provides `/feishu_auth_all` for guided authorization of the current MVP tools.
+- Includes first read-only native tools for contacts, users, group messages, and Drive files.
+- Pairs with the background task runtime so long work can ask the parent chat
+  for missing input and then resume cleanly.
+
+### Telegram And WeChat Entrypoints
+
+Feishu is the current native/runtime-first path, but ControlMesh is not a
+Feishu-only product:
+
+- Telegram: mature token-based entrypoint for personal DMs, groups, always-on
+  task bots, and file delivery.
+- WeChat/Weixin: existing Weixin iLink entrypoint with QR login, long-poll
+  inbound messages, and reply context after the first WeChat message.
+- Matrix: secondary compatibility transport for teams already using
+  Matrix/Element.
+
+Bridge mode, Matrix, sub-agents, cron, webhooks, and API remain available. The
+public product story now centers on Feishu native plus Telegram and WeChat
+entrypoints.
+
+### Runtime primitives
+
+- `/tasks/create`
+- `/tasks/resume`
+- `/tasks/ask_parent`
+- `/tasks/list`
+- `/interagent/send`
+
+### Quick Start
+
+```bash
+pipx install controlmesh
+controlmesh
+```
+
+To track the latest GitHub `main` directly instead of waiting for the next PyPI release:
+
+```bash
+pipx install "git+https://github.com/muqiao215/ControlMesh.git@main"
+controlmesh
+```
+
+Run from source:
+
+```bash
+git clone https://github.com/muqiao215/ControlMesh.git
+cd ControlMesh
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[matrix,api]"
+controlmesh
+```
+
+### Feishu Setup
+
+Native mode:
+
+```bash
+controlmesh feishu native bootstrap
+controlmesh auth feishu setup
+controlmesh auth feishu register-begin
+controlmesh auth feishu register-poll --device-code "<device_code>" --interval 5 --expires-in 600
+controlmesh auth feishu doctor
+controlmesh auth feishu probe
+```
+
+Task runtime:
+
+```bash
+controlmesh tasks doctor
+controlmesh tasks list
+```
+
+### Documentation
+
+- Installation: [`docs/installation.md`](docs/installation.md)
+- Feishu setup: [`docs/feishu-setup.md`](docs/feishu-setup.md)
+- Telegram setup: [`docs/telegram-setup.md`](docs/telegram-setup.md)
+- WeChat/Weixin setup: [`docs/weixin-setup.md`](docs/weixin-setup.md)
+- Case-pack contract: [`docs/case-pack/README.md`](docs/case-pack/README.md)
+- Documentation index: [`docs/README.md`](docs/README.md)
+- Example config: [`config.example.json`](config.example.json)
+
+### License
+
+MIT License. See [`LICENSE`](LICENSE).