+ nanobot: Ultra-Lightweight Personal AI Assistant
+
+ 
\ No newline at end of file
diff --git a/nanobot/Dockerfile b/nanobot/Dockerfile
new file mode 100644
index 0000000..8132747
--- /dev/null
+++ b/nanobot/Dockerfile
@@ -0,0 +1,40 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+# Install Node.js 20 for the WhatsApp bridge
+RUN apt-get update && \
+ apt-get install -y --no-install-recommends curl ca-certificates gnupg git && \
+ mkdir -p /etc/apt/keyrings && \
+ curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
+ echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \
+ apt-get update && \
+ apt-get install -y --no-install-recommends nodejs && \
+ apt-get purge -y gnupg && \
+ apt-get autoremove -y && \
+ rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies first (cached layer)
+COPY pyproject.toml README.md LICENSE ./
+RUN mkdir -p nanobot bridge && touch nanobot/__init__.py && \
+ uv pip install --system --no-cache . && \
+ rm -rf nanobot bridge
+
+# Copy the full source and install
+COPY nanobot/ nanobot/
+COPY bridge/ bridge/
+RUN uv pip install --system --no-cache .
+
+# Build the WhatsApp bridge
+WORKDIR /app/bridge
+RUN npm install && npm run build
+WORKDIR /app
+
+# Create config directory
+RUN mkdir -p /root/.nanobot
+
+# Gateway default port
+EXPOSE 18790
+
+ENTRYPOINT ["nanobot"]
+CMD ["status"]
diff --git a/nanobot/LICENSE b/nanobot/LICENSE
new file mode 100644
index 0000000..24bdacc
--- /dev/null
+++ b/nanobot/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nanobot contributors
+
+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.
\ No newline at end of file
diff --git a/nanobot/README.md b/nanobot/README.md
new file mode 100644
index 0000000..13971e2
--- /dev/null
+++ b/nanobot/README.md
@@ -0,0 +1,1205 @@
+
+
+
+ 
+
📈 24/7 Real-Time Market Analysis |
+ 🚀 Full-Stack Software Engineer |
+ 📅 Smart Daily Routine Manager |
+ 📚 Personal Knowledge Assistant |
+
|---|---|---|---|
|
+
|
+
|
+
|
+
| Discovery • Insights • Trends | +Develop • Deploy • Scale | +Schedule • Automate • Organize | +Learn • Memory • Reasoning | +
+ Thanks for visiting ✨ nanobot!
+
+
+ nanobot is for educational, research, and technical exchange purposes only +
diff --git a/nanobot/SECURITY.md b/nanobot/SECURITY.md new file mode 100644 index 0000000..af4da71 --- /dev/null +++ b/nanobot/SECURITY.md @@ -0,0 +1,263 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in nanobot, please report it by: + +1. **DO NOT** open a public GitHub issue +2. Create a private security advisory on GitHub or contact the repository maintainers (xubinrencs@gmail.com) +3. Include: + - Description of the vulnerability + - Steps to reproduce + - Potential impact + - Suggested fix (if any) + +We aim to respond to security reports within 48 hours. + +## Security Best Practices + +### 1. API Key Management + +**CRITICAL**: Never commit API keys to version control. + +```bash +# ✅ Good: Store in config file with restricted permissions +chmod 600 ~/.nanobot/config.json + +# ❌ Bad: Hardcoding keys in code or committing them +``` + +**Recommendations:** +- Store API keys in `~/.nanobot/config.json` with file permissions set to `0600` +- Consider using environment variables for sensitive keys +- Use OS keyring/credential manager for production deployments +- Rotate API keys regularly +- Use separate API keys for development and production + +### 2. Channel Access Control + +**IMPORTANT**: Always configure `allowFrom` lists for production use. + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["123456789", "987654321"] + }, + "whatsapp": { + "enabled": true, + "allowFrom": ["+1234567890"] + } + } +} +``` + +**Security Notes:** +- In `v0.1.4.post3` and earlier, an empty `allowFrom` allows all users. In newer versions (including source builds), **empty `allowFrom` denies all access** — set `["*"]` to explicitly allow everyone. +- Get your Telegram user ID from `@userinfobot` +- Use full phone numbers with country code for WhatsApp +- Review access logs regularly for unauthorized access attempts + +### 3. Shell Command Execution + +The `exec` tool can execute shell commands. While dangerous command patterns are blocked, you should: + +- ✅ Review all tool usage in agent logs +- ✅ Understand what commands the agent is running +- ✅ Use a dedicated user account with limited privileges +- ✅ Never run nanobot as root +- ❌ Don't disable security checks +- ❌ Don't run on systems with sensitive data without careful review + +**Blocked patterns:** +- `rm -rf /` - Root filesystem deletion +- Fork bombs +- Filesystem formatting (`mkfs.*`) +- Raw disk writes +- Other destructive operations + +### 4. File System Access + +File operations have path traversal protection, but: + +- ✅ Run nanobot with a dedicated user account +- ✅ Use filesystem permissions to protect sensitive directories +- ✅ Regularly audit file operations in logs +- ❌ Don't give unrestricted access to sensitive files + +### 5. Network Security + +**API Calls:** +- All external API calls use HTTPS by default +- Timeouts are configured to prevent hanging requests +- Consider using a firewall to restrict outbound connections if needed + +**WhatsApp Bridge:** +- The bridge binds to `127.0.0.1:3001` (localhost only, not accessible from external network) +- Set `bridgeToken` in config to enable shared-secret authentication between Python and Node.js +- Keep authentication data in `~/.nanobot/whatsapp-auth` secure (mode 0700) + +### 6. Dependency Security + +**Critical**: Keep dependencies updated! + +```bash +# Check for vulnerable dependencies +pip install pip-audit +pip-audit + +# Update to latest secure versions +pip install --upgrade nanobot-ai +``` + +For Node.js dependencies (WhatsApp bridge): +```bash +cd bridge +npm audit +npm audit fix +``` + +**Important Notes:** +- Keep `litellm` updated to the latest version for security fixes +- We've updated `ws` to `>=8.17.1` to fix DoS vulnerability +- Run `pip-audit` or `npm audit` regularly +- Subscribe to security advisories for nanobot and its dependencies + +### 7. Production Deployment + +For production use: + +1. **Isolate the Environment** + ```bash + # Run in a container or VM + docker run --rm -it python:3.11 + pip install nanobot-ai + ``` + +2. **Use a Dedicated User** + ```bash + sudo useradd -m -s /bin/bash nanobot + sudo -u nanobot nanobot gateway + ``` + +3. **Set Proper Permissions** + ```bash + chmod 700 ~/.nanobot + chmod 600 ~/.nanobot/config.json + chmod 700 ~/.nanobot/whatsapp-auth + ``` + +4. **Enable Logging** + ```bash + # Configure log monitoring + tail -f ~/.nanobot/logs/nanobot.log + ``` + +5. **Use Rate Limiting** + - Configure rate limits on your API providers + - Monitor usage for anomalies + - Set spending limits on LLM APIs + +6. **Regular Updates** + ```bash + # Check for updates weekly + pip install --upgrade nanobot-ai + ``` + +### 8. Development vs Production + +**Development:** +- Use separate API keys +- Test with non-sensitive data +- Enable verbose logging +- Use a test Telegram bot + +**Production:** +- Use dedicated API keys with spending limits +- Restrict file system access +- Enable audit logging +- Regular security reviews +- Monitor for unusual activity + +### 9. Data Privacy + +- **Logs may contain sensitive information** - secure log files appropriately +- **LLM providers see your prompts** - review their privacy policies +- **Chat history is stored locally** - protect the `~/.nanobot` directory +- **API keys are in plain text** - use OS keyring for production + +### 10. Incident Response + +If you suspect a security breach: + +1. **Immediately revoke compromised API keys** +2. **Review logs for unauthorized access** + ```bash + grep "Access denied" ~/.nanobot/logs/nanobot.log + ``` +3. **Check for unexpected file modifications** +4. **Rotate all credentials** +5. **Update to latest version** +6. **Report the incident** to maintainers + +## Security Features + +### Built-in Security Controls + +✅ **Input Validation** +- Path traversal protection on file operations +- Dangerous command pattern detection +- Input length limits on HTTP requests + +✅ **Authentication** +- Allow-list based access control — in `v0.1.4.post3` and earlier empty means allow all; in newer versions empty means deny all (`["*"]` to explicitly allow all) +- Failed authentication attempt logging + +✅ **Resource Protection** +- Command execution timeouts (60s default) +- Output truncation (10KB limit) +- HTTP request timeouts (10-30s) + +✅ **Secure Communication** +- HTTPS for all external API calls +- TLS for Telegram API +- WhatsApp bridge: localhost-only binding + optional token auth + +## Known Limitations + +⚠️ **Current Security Limitations:** + +1. **No Rate Limiting** - Users can send unlimited messages (add your own if needed) +2. **Plain Text Config** - API keys stored in plain text (use keyring for production) +3. **No Session Management** - No automatic session expiry +4. **Limited Command Filtering** - Only blocks obvious dangerous patterns +5. **No Audit Trail** - Limited security event logging (enhance as needed) + +## Security Checklist + +Before deploying nanobot: + +- [ ] API keys stored securely (not in code) +- [ ] Config file permissions set to 0600 +- [ ] `allowFrom` lists configured for all channels +- [ ] Running as non-root user +- [ ] File system permissions properly restricted +- [ ] Dependencies updated to latest secure versions +- [ ] Logs monitored for security events +- [ ] Rate limits configured on API providers +- [ ] Backup and disaster recovery plan in place +- [ ] Security review of custom skills/tools + +## Updates + +**Last Updated**: 2026-02-03 + +For the latest security updates and announcements, check: +- GitHub Security Advisories: https://github.com/HKUDS/nanobot/security/advisories +- Release Notes: https://github.com/HKUDS/nanobot/releases + +## License + +See LICENSE file for details. diff --git a/nanobot/bridge/package.json b/nanobot/bridge/package.json new file mode 100644 index 0000000..e91517c --- /dev/null +++ b/nanobot/bridge/package.json @@ -0,0 +1,26 @@ +{ + "name": "nanobot-whatsapp-bridge", + "version": "0.1.0", + "description": "WhatsApp bridge for nanobot using Baileys", + "type": "module", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsc && node dist/index.js" + }, + "dependencies": { + "@whiskeysockets/baileys": "7.0.0-rc.9", + "ws": "^8.17.1", + "qrcode-terminal": "^0.12.0", + "pino": "^9.0.0" + }, + "devDependencies": { + "@types/node": "^20.14.0", + "@types/ws": "^8.5.10", + "typescript": "^5.4.0" + }, + "engines": { + "node": ">=20.0.0" + } +} diff --git a/nanobot/bridge/src/index.ts b/nanobot/bridge/src/index.ts new file mode 100644 index 0000000..e8f3db9 --- /dev/null +++ b/nanobot/bridge/src/index.ts @@ -0,0 +1,51 @@ +#!/usr/bin/env node +/** + * nanobot WhatsApp Bridge + * + * This bridge connects WhatsApp Web to nanobot's Python backend + * via WebSocket. It handles authentication, message forwarding, + * and reconnection logic. + * + * Usage: + * npm run build && npm start + * + * Or with custom settings: + * BRIDGE_PORT=3001 AUTH_DIR=~/.nanobot/whatsapp npm start + */ + +// Polyfill crypto for Baileys in ESM +import { webcrypto } from 'crypto'; +if (!globalThis.crypto) { + (globalThis as any).crypto = webcrypto; +} + +import { BridgeServer } from './server.js'; +import { homedir } from 'os'; +import { join } from 'path'; + +const PORT = parseInt(process.env.BRIDGE_PORT || '3001', 10); +const AUTH_DIR = process.env.AUTH_DIR || join(homedir(), '.nanobot', 'whatsapp-auth'); +const TOKEN = process.env.BRIDGE_TOKEN || undefined; + +console.log('🐈 nanobot WhatsApp Bridge'); +console.log('========================\n'); + +const server = new BridgeServer(PORT, AUTH_DIR, TOKEN); + +// Handle graceful shutdown +process.on('SIGINT', async () => { + console.log('\n\nShutting down...'); + await server.stop(); + process.exit(0); +}); + +process.on('SIGTERM', async () => { + await server.stop(); + process.exit(0); +}); + +// Start the server +server.start().catch((error) => { + console.error('Failed to start bridge:', error); + process.exit(1); +}); diff --git a/nanobot/bridge/src/server.ts b/nanobot/bridge/src/server.ts new file mode 100644 index 0000000..7d48f5e --- /dev/null +++ b/nanobot/bridge/src/server.ts @@ -0,0 +1,129 @@ +/** + * WebSocket server for Python-Node.js bridge communication. + * Security: binds to 127.0.0.1 only; optional BRIDGE_TOKEN auth. + */ + +import { WebSocketServer, WebSocket } from 'ws'; +import { WhatsAppClient, InboundMessage } from './whatsapp.js'; + +interface SendCommand { + type: 'send'; + to: string; + text: string; +} + +interface BridgeMessage { + type: 'message' | 'status' | 'qr' | 'error'; + [key: string]: unknown; +} + +export class BridgeServer { + private wss: WebSocketServer | null = null; + private wa: WhatsAppClient | null = null; + private clients: Settext
to keep payload minimal. + if formatted.startswith("") and formatted.endswith("
"): + inner = formatted[3:-4] + if "<" not in inner and ">" not in inner: + return None + return formatted + + +def _build_matrix_text_content(text: str) -> dict[str, object]: + """Build Matrix m.text payload with optional HTML formatted_body.""" + content: dict[str, object] = {"msgtype": "m.text", "body": text, "m.mentions": {}} + if html := _render_markdown_html(text): + content["format"] = MATRIX_HTML_FORMAT + content["formatted_body"] = html + return content + + +class _NioLoguruHandler(logging.Handler): + """Route matrix-nio stdlib logs into Loguru.""" + + def emit(self, record: logging.LogRecord) -> None: + try: + level = logger.level(record.levelname).name + except ValueError: + level = record.levelno + frame, depth = logging.currentframe(), 2 + while frame and frame.f_code.co_filename == logging.__file__: + frame, depth = frame.f_back, depth + 1 + logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage()) + + +def _configure_nio_logging_bridge() -> None: + """Bridge matrix-nio logs to Loguru (idempotent).""" + nio_logger = logging.getLogger("nio") + if not any(isinstance(h, _NioLoguruHandler) for h in nio_logger.handlers): + nio_logger.handlers = [_NioLoguruHandler()] + nio_logger.propagate = False + + +class MatrixChannel(BaseChannel): + """Matrix (Element) channel using long-polling sync.""" + + name = "matrix" + + def __init__(self, config: Any, bus, *, restrict_to_workspace: bool = False, + workspace: Path | None = None): + super().__init__(config, bus) + self.client: AsyncClient | None = None + self._sync_task: asyncio.Task | None = None + self._typing_tasks: dict[str, asyncio.Task] = {} + self._restrict_to_workspace = restrict_to_workspace + self._workspace = workspace.expanduser().resolve() if workspace else None + self._server_upload_limit_bytes: int | None = None + self._server_upload_limit_checked = False + + async def start(self) -> None: + """Start Matrix client and begin sync loop.""" + self._running = True + _configure_nio_logging_bridge() + + store_path = get_data_dir() / "matrix-store" + store_path.mkdir(parents=True, exist_ok=True) + + self.client = AsyncClient( + homeserver=self.config.homeserver, user=self.config.user_id, + store_path=store_path, + config=AsyncClientConfig(store_sync_tokens=True, encryption_enabled=self.config.e2ee_enabled), + ) + self.client.user_id = self.config.user_id + self.client.access_token = self.config.access_token + self.client.device_id = self.config.device_id + + self._register_event_callbacks() + self._register_response_callbacks() + + if not self.config.e2ee_enabled: + logger.warning("Matrix E2EE disabled; encrypted rooms may be undecryptable.") + + if self.config.device_id: + try: + self.client.load_store() + except Exception: + logger.exception("Matrix store load failed; restart may replay recent messages.") + else: + logger.warning("Matrix device_id empty; restart may replay recent messages.") + + self._sync_task = asyncio.create_task(self._sync_loop()) + + async def stop(self) -> None: + """Stop the Matrix channel with graceful sync shutdown.""" + self._running = False + for room_id in list(self._typing_tasks): + await self._stop_typing_keepalive(room_id, clear_typing=False) + if self.client: + self.client.stop_sync_forever() + if self._sync_task: + try: + await asyncio.wait_for(asyncio.shield(self._sync_task), + timeout=self.config.sync_stop_grace_seconds) + except (asyncio.TimeoutError, asyncio.CancelledError): + self._sync_task.cancel() + try: + await self._sync_task + except asyncio.CancelledError: + pass + if self.client: + await self.client.close() + + def _is_workspace_path_allowed(self, path: Path) -> bool: + """Check path is inside workspace (when restriction enabled).""" + if not self._restrict_to_workspace or not self._workspace: + return True + try: + path.resolve(strict=False).relative_to(self._workspace) + return True + except ValueError: + return False + + def _collect_outbound_media_candidates(self, media: list[str]) -> list[Path]: + """Deduplicate and resolve outbound attachment paths.""" + seen: set[str] = set() + candidates: list[Path] = [] + for raw in media: + if not isinstance(raw, str) or not raw.strip(): + continue + path = Path(raw.strip()).expanduser() + try: + key = str(path.resolve(strict=False)) + except OSError: + key = str(path) + if key not in seen: + seen.add(key) + candidates.append(path) + return candidates + + @staticmethod + def _build_outbound_attachment_content( + *, filename: str, mime: str, size_bytes: int, + mxc_url: str, encryption_info: dict[str, Any] | None = None, + ) -> dict[str, Any]: + """Build Matrix content payload for an uploaded file/image/audio/video.""" + prefix = mime.split("/")[0] + msgtype = {"image": "m.image", "audio": "m.audio", "video": "m.video"}.get(prefix, "m.file") + content: dict[str, Any] = { + "msgtype": msgtype, "body": filename, "filename": filename, + "info": {"mimetype": mime, "size": size_bytes}, "m.mentions": {}, + } + if encryption_info: + content["file"] = {**encryption_info, "url": mxc_url} + else: + content["url"] = mxc_url + return content + + def _is_encrypted_room(self, room_id: str) -> bool: + if not self.client: + return False + room = getattr(self.client, "rooms", {}).get(room_id) + return bool(getattr(room, "encrypted", False)) + + async def _send_room_content(self, room_id: str, content: dict[str, Any]) -> None: + """Send m.room.message with E2EE options.""" + if not self.client: + return + kwargs: dict[str, Any] = {"room_id": room_id, "message_type": "m.room.message", "content": content} + if self.config.e2ee_enabled: + kwargs["ignore_unverified_devices"] = True + await self.client.room_send(**kwargs) + + async def _resolve_server_upload_limit_bytes(self) -> int | None: + """Query homeserver upload limit once per channel lifecycle.""" + if self._server_upload_limit_checked: + return self._server_upload_limit_bytes + self._server_upload_limit_checked = True + if not self.client: + return None + try: + response = await self.client.content_repository_config() + except Exception: + return None + upload_size = getattr(response, "upload_size", None) + if isinstance(upload_size, int) and upload_size > 0: + self._server_upload_limit_bytes = upload_size + return upload_size + return None + + async def _effective_media_limit_bytes(self) -> int: + """min(local config, server advertised) — 0 blocks all uploads.""" + local_limit = max(int(self.config.max_media_bytes), 0) + server_limit = await self._resolve_server_upload_limit_bytes() + if server_limit is None: + return local_limit + return min(local_limit, server_limit) if local_limit else 0 + + async def _upload_and_send_attachment( + self, room_id: str, path: Path, limit_bytes: int, + relates_to: dict[str, Any] | None = None, + ) -> str | None: + """Upload one local file to Matrix and send it as a media message. Returns failure marker or None.""" + if not self.client: + return _ATTACH_UPLOAD_FAILED.format(path.name or _DEFAULT_ATTACH_NAME) + + resolved = path.expanduser().resolve(strict=False) + filename = safe_filename(resolved.name) or _DEFAULT_ATTACH_NAME + fail = _ATTACH_UPLOAD_FAILED.format(filename) + + if not resolved.is_file() or not self._is_workspace_path_allowed(resolved): + return fail + try: + size_bytes = resolved.stat().st_size + except OSError: + return fail + if limit_bytes <= 0 or size_bytes > limit_bytes: + return _ATTACH_TOO_LARGE.format(filename) + + mime = mimetypes.guess_type(filename, strict=False)[0] or "application/octet-stream" + try: + with resolved.open("rb") as f: + upload_result = await self.client.upload( + f, content_type=mime, filename=filename, + encrypt=self.config.e2ee_enabled and self._is_encrypted_room(room_id), + filesize=size_bytes, + ) + except Exception: + return fail + + upload_response = upload_result[0] if isinstance(upload_result, tuple) else upload_result + encryption_info = upload_result[1] if isinstance(upload_result, tuple) and isinstance(upload_result[1], dict) else None + if isinstance(upload_response, UploadError): + return fail + mxc_url = getattr(upload_response, "content_uri", None) + if not isinstance(mxc_url, str) or not mxc_url.startswith("mxc://"): + return fail + + content = self._build_outbound_attachment_content( + filename=filename, mime=mime, size_bytes=size_bytes, + mxc_url=mxc_url, encryption_info=encryption_info, + ) + if relates_to: + content["m.relates_to"] = relates_to + try: + await self._send_room_content(room_id, content) + except Exception: + return fail + return None + + async def send(self, msg: OutboundMessage) -> None: + """Send outbound content; clear typing for non-progress messages.""" + if not self.client: + return + text = msg.content or "" + candidates = self._collect_outbound_media_candidates(msg.media) + relates_to = self._build_thread_relates_to(msg.metadata) + is_progress = bool((msg.metadata or {}).get("_progress")) + try: + failures: list[str] = [] + if candidates: + limit_bytes = await self._effective_media_limit_bytes() + for path in candidates: + if fail := await self._upload_and_send_attachment( + room_id=msg.chat_id, + path=path, + limit_bytes=limit_bytes, + relates_to=relates_to, + ): + failures.append(fail) + if failures: + text = f"{text.rstrip()}\n{chr(10).join(failures)}" if text.strip() else "\n".join(failures) + if text or not candidates: + content = _build_matrix_text_content(text) + if relates_to: + content["m.relates_to"] = relates_to + await self._send_room_content(msg.chat_id, content) + finally: + if not is_progress: + await self._stop_typing_keepalive(msg.chat_id, clear_typing=True) + + def _register_event_callbacks(self) -> None: + self.client.add_event_callback(self._on_message, RoomMessageText) + self.client.add_event_callback(self._on_media_message, MATRIX_MEDIA_EVENT_FILTER) + self.client.add_event_callback(self._on_room_invite, InviteEvent) + + def _register_response_callbacks(self) -> None: + self.client.add_response_callback(self._on_sync_error, SyncError) + self.client.add_response_callback(self._on_join_error, JoinError) + self.client.add_response_callback(self._on_send_error, RoomSendError) + + def _log_response_error(self, label: str, response: Any) -> None: + """Log Matrix response errors — auth errors at ERROR level, rest at WARNING.""" + code = getattr(response, "status_code", None) + is_auth = code in {"M_UNKNOWN_TOKEN", "M_FORBIDDEN", "M_UNAUTHORIZED"} + is_fatal = is_auth or getattr(response, "soft_logout", False) + (logger.error if is_fatal else logger.warning)("Matrix {} failed: {}", label, response) + + async def _on_sync_error(self, response: SyncError) -> None: + self._log_response_error("sync", response) + + async def _on_join_error(self, response: JoinError) -> None: + self._log_response_error("join", response) + + async def _on_send_error(self, response: RoomSendError) -> None: + self._log_response_error("send", response) + + async def _set_typing(self, room_id: str, typing: bool) -> None: + """Best-effort typing indicator update.""" + if not self.client: + return + try: + response = await self.client.room_typing(room_id=room_id, typing_state=typing, + timeout=TYPING_NOTICE_TIMEOUT_MS) + if isinstance(response, RoomTypingError): + logger.debug("Matrix typing failed for {}: {}", room_id, response) + except Exception: + pass + + async def _start_typing_keepalive(self, room_id: str) -> None: + """Start periodic typing refresh (spec-recommended keepalive).""" + await self._stop_typing_keepalive(room_id, clear_typing=False) + await self._set_typing(room_id, True) + if not self._running: + return + + async def loop() -> None: + try: + while self._running: + await asyncio.sleep(TYPING_KEEPALIVE_INTERVAL_MS / 1000) + await self._set_typing(room_id, True) + except asyncio.CancelledError: + pass + + self._typing_tasks[room_id] = asyncio.create_task(loop()) + + async def _stop_typing_keepalive(self, room_id: str, *, clear_typing: bool) -> None: + if task := self._typing_tasks.pop(room_id, None): + task.cancel() + try: + await task + except asyncio.CancelledError: + pass + if clear_typing: + await self._set_typing(room_id, False) + + async def _sync_loop(self) -> None: + while self._running: + try: + await self.client.sync_forever(timeout=30000, full_state=True) + except asyncio.CancelledError: + break + except Exception: + await asyncio.sleep(2) + + async def _on_room_invite(self, room: MatrixRoom, event: InviteEvent) -> None: + if self.is_allowed(event.sender): + await self.client.join(room.room_id) + + def _is_direct_room(self, room: MatrixRoom) -> bool: + count = getattr(room, "member_count", None) + return isinstance(count, int) and count <= 2 + + def _is_bot_mentioned(self, event: RoomMessage) -> bool: + """Check m.mentions payload for bot mention.""" + source = getattr(event, "source", None) + if not isinstance(source, dict): + return False + mentions = (source.get("content") or {}).get("m.mentions") + if not isinstance(mentions, dict): + return False + user_ids = mentions.get("user_ids") + if isinstance(user_ids, list) and self.config.user_id in user_ids: + return True + return bool(self.config.allow_room_mentions and mentions.get("room") is True) + + def _should_process_message(self, room: MatrixRoom, event: RoomMessage) -> bool: + """Apply sender and room policy checks.""" + if not self.is_allowed(event.sender): + return False + if self._is_direct_room(room): + return True + policy = self.config.group_policy + if policy == "open": + return True + if policy == "allowlist": + return room.room_id in (self.config.group_allow_from or []) + if policy == "mention": + return self._is_bot_mentioned(event) + return False + + def _media_dir(self) -> Path: + return get_media_dir("matrix") + + @staticmethod + def _event_source_content(event: RoomMessage) -> dict[str, Any]: + source = getattr(event, "source", None) + if not isinstance(source, dict): + return {} + content = source.get("content") + return content if isinstance(content, dict) else {} + + def _event_thread_root_id(self, event: RoomMessage) -> str | None: + relates_to = self._event_source_content(event).get("m.relates_to") + if not isinstance(relates_to, dict) or relates_to.get("rel_type") != "m.thread": + return None + root_id = relates_to.get("event_id") + return root_id if isinstance(root_id, str) and root_id else None + + def _thread_metadata(self, event: RoomMessage) -> dict[str, str] | None: + if not (root_id := self._event_thread_root_id(event)): + return None + meta: dict[str, str] = {"thread_root_event_id": root_id} + if isinstance(reply_to := getattr(event, "event_id", None), str) and reply_to: + meta["thread_reply_to_event_id"] = reply_to + return meta + + @staticmethod + def _build_thread_relates_to(metadata: dict[str, Any] | None) -> dict[str, Any] | None: + if not metadata: + return None + root_id = metadata.get("thread_root_event_id") + if not isinstance(root_id, str) or not root_id: + return None + reply_to = metadata.get("thread_reply_to_event_id") or metadata.get("event_id") + if not isinstance(reply_to, str) or not reply_to: + return None + return {"rel_type": "m.thread", "event_id": root_id, + "m.in_reply_to": {"event_id": reply_to}, "is_falling_back": True} + + def _event_attachment_type(self, event: MatrixMediaEvent) -> str: + msgtype = self._event_source_content(event).get("msgtype") + return _MSGTYPE_MAP.get(msgtype, "file") + + @staticmethod + def _is_encrypted_media_event(event: MatrixMediaEvent) -> bool: + return (isinstance(getattr(event, "key", None), dict) + and isinstance(getattr(event, "hashes", None), dict) + and isinstance(getattr(event, "iv", None), str)) + + def _event_declared_size_bytes(self, event: MatrixMediaEvent) -> int | None: + info = self._event_source_content(event).get("info") + size = info.get("size") if isinstance(info, dict) else None + return size if isinstance(size, int) and size >= 0 else None + + def _event_mime(self, event: MatrixMediaEvent) -> str | None: + info = self._event_source_content(event).get("info") + if isinstance(info, dict) and isinstance(m := info.get("mimetype"), str) and m: + return m + m = getattr(event, "mimetype", None) + return m if isinstance(m, str) and m else None + + def _event_filename(self, event: MatrixMediaEvent, attachment_type: str) -> str: + body = getattr(event, "body", None) + if isinstance(body, str) and body.strip(): + if candidate := safe_filename(Path(body).name): + return candidate + return _DEFAULT_ATTACH_NAME if attachment_type == "file" else attachment_type + + def _build_attachment_path(self, event: MatrixMediaEvent, attachment_type: str, + filename: str, mime: str | None) -> Path: + safe_name = safe_filename(Path(filename).name) or _DEFAULT_ATTACH_NAME + suffix = Path(safe_name).suffix + if not suffix and mime: + if guessed := mimetypes.guess_extension(mime, strict=False): + safe_name, suffix = f"{safe_name}{guessed}", guessed + stem = (Path(safe_name).stem or attachment_type)[:72] + suffix = suffix[:16] + event_id = safe_filename(str(getattr(event, "event_id", "") or "evt").lstrip("$")) + event_prefix = (event_id[:24] or "evt").strip("_") + return self._media_dir() / f"{event_prefix}_{stem}{suffix}" + + async def _download_media_bytes(self, mxc_url: str) -> bytes | None: + if not self.client: + return None + response = await self.client.download(mxc=mxc_url) + if isinstance(response, DownloadError): + logger.warning("Matrix download failed for {}: {}", mxc_url, response) + return None + body = getattr(response, "body", None) + if isinstance(body, (bytes, bytearray)): + return bytes(body) + if isinstance(response, MemoryDownloadResponse): + return bytes(response.body) + if isinstance(body, (str, Path)): + path = Path(body) + if path.is_file(): + try: + return path.read_bytes() + except OSError: + return None + return None + + def _decrypt_media_bytes(self, event: MatrixMediaEvent, ciphertext: bytes) -> bytes | None: + key_obj, hashes, iv = getattr(event, "key", None), getattr(event, "hashes", None), getattr(event, "iv", None) + key = key_obj.get("k") if isinstance(key_obj, dict) else None + sha256 = hashes.get("sha256") if isinstance(hashes, dict) else None + if not all(isinstance(v, str) for v in (key, sha256, iv)): + return None + try: + return decrypt_attachment(ciphertext, key, sha256, iv) + except (EncryptionError, ValueError, TypeError): + logger.warning("Matrix decrypt failed for event {}", getattr(event, "event_id", "")) + return None + + async def _fetch_media_attachment( + self, room: MatrixRoom, event: MatrixMediaEvent, + ) -> tuple[dict[str, Any] | None, str]: + """Download, decrypt if needed, and persist a Matrix attachment.""" + atype = self._event_attachment_type(event) + mime = self._event_mime(event) + filename = self._event_filename(event, atype) + mxc_url = getattr(event, "url", None) + fail = _ATTACH_FAILED.format(filename) + + if not isinstance(mxc_url, str) or not mxc_url.startswith("mxc://"): + return None, fail + + limit_bytes = await self._effective_media_limit_bytes() + declared = self._event_declared_size_bytes(event) + if declared is not None and declared > limit_bytes: + return None, _ATTACH_TOO_LARGE.format(filename) + + downloaded = await self._download_media_bytes(mxc_url) + if downloaded is None: + return None, fail + + encrypted = self._is_encrypted_media_event(event) + data = downloaded + if encrypted: + if (data := self._decrypt_media_bytes(event, downloaded)) is None: + return None, fail + + if len(data) > limit_bytes: + return None, _ATTACH_TOO_LARGE.format(filename) + + path = self._build_attachment_path(event, atype, filename, mime) + try: + path.write_bytes(data) + except OSError: + return None, fail + + attachment = { + "type": atype, "mime": mime, "filename": filename, + "event_id": str(getattr(event, "event_id", "") or ""), + "encrypted": encrypted, "size_bytes": len(data), + "path": str(path), "mxc_url": mxc_url, + } + return attachment, _ATTACH_MARKER.format(path) + + def _base_metadata(self, room: MatrixRoom, event: RoomMessage) -> dict[str, Any]: + """Build common metadata for text and media handlers.""" + meta: dict[str, Any] = {"room": getattr(room, "display_name", room.room_id)} + if isinstance(eid := getattr(event, "event_id", None), str) and eid: + meta["event_id"] = eid + if thread := self._thread_metadata(event): + meta.update(thread) + return meta + + async def _on_message(self, room: MatrixRoom, event: RoomMessageText) -> None: + if event.sender == self.config.user_id or not self._should_process_message(room, event): + return + await self._start_typing_keepalive(room.room_id) + try: + await self._handle_message( + sender_id=event.sender, chat_id=room.room_id, + content=event.body, metadata=self._base_metadata(room, event), + ) + except Exception: + await self._stop_typing_keepalive(room.room_id, clear_typing=True) + raise + + async def _on_media_message(self, room: MatrixRoom, event: MatrixMediaEvent) -> None: + if event.sender == self.config.user_id or not self._should_process_message(room, event): + return + attachment, marker = await self._fetch_media_attachment(room, event) + parts: list[str] = [] + if isinstance(body := getattr(event, "body", None), str) and body.strip(): + parts.append(body.strip()) + if marker: + parts.append(marker) + + await self._start_typing_keepalive(room.room_id) + try: + meta = self._base_metadata(room, event) + meta["attachments"] = [] + if attachment: + meta["attachments"] = [attachment] + await self._handle_message( + sender_id=event.sender, chat_id=room.room_id, + content="\n".join(parts), + media=[attachment["path"]] if attachment else [], + metadata=meta, + ) + except Exception: + await self._stop_typing_keepalive(room.room_id, clear_typing=True) + raise diff --git a/nanobot/nanobot/channels/mochat.py b/nanobot/nanobot/channels/mochat.py new file mode 100644 index 0000000..09e31c3 --- /dev/null +++ b/nanobot/nanobot/channels/mochat.py @@ -0,0 +1,895 @@ +"""Mochat channel implementation using Socket.IO with HTTP polling fallback.""" + +from __future__ import annotations + +import asyncio +import json +from collections import deque +from dataclasses import dataclass, field +from datetime import datetime +from typing import Any + +import httpx +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_runtime_subdir +from nanobot.config.schema import MochatConfig + +try: + import socketio + SOCKETIO_AVAILABLE = True +except ImportError: + socketio = None + SOCKETIO_AVAILABLE = False + +try: + import msgpack # noqa: F401 + MSGPACK_AVAILABLE = True +except ImportError: + MSGPACK_AVAILABLE = False + +MAX_SEEN_MESSAGE_IDS = 2000 +CURSOR_SAVE_DEBOUNCE_S = 0.5 + + +# --------------------------------------------------------------------------- +# Data classes +# --------------------------------------------------------------------------- + +@dataclass +class MochatBufferedEntry: + """Buffered inbound entry for delayed dispatch.""" + raw_body: str + author: str + sender_name: str = "" + sender_username: str = "" + timestamp: int | None = None + message_id: str = "" + group_id: str = "" + + +@dataclass +class DelayState: + """Per-target delayed message state.""" + entries: list[MochatBufferedEntry] = field(default_factory=list) + lock: asyncio.Lock = field(default_factory=asyncio.Lock) + timer: asyncio.Task | None = None + + +@dataclass +class MochatTarget: + """Outbound target resolution result.""" + id: str + is_panel: bool + + +# --------------------------------------------------------------------------- +# Pure helpers +# --------------------------------------------------------------------------- + +def _safe_dict(value: Any) -> dict: + """Return *value* if it's a dict, else empty dict.""" + return value if isinstance(value, dict) else {} + + +def _str_field(src: dict, *keys: str) -> str: + """Return the first non-empty str value found for *keys*, stripped.""" + for k in keys: + v = src.get(k) + if isinstance(v, str) and v.strip(): + return v.strip() + return "" + + +def _make_synthetic_event( + message_id: str, author: str, content: Any, + meta: Any, group_id: str, converse_id: str, + timestamp: Any = None, *, author_info: Any = None, +) -> dict[str, Any]: + """Build a synthetic ``message.add`` event dict.""" + payload: dict[str, Any] = { + "messageId": message_id, "author": author, + "content": content, "meta": _safe_dict(meta), + "groupId": group_id, "converseId": converse_id, + } + if author_info is not None: + payload["authorInfo"] = _safe_dict(author_info) + return { + "type": "message.add", + "timestamp": timestamp or datetime.utcnow().isoformat(), + "payload": payload, + } + + +def normalize_mochat_content(content: Any) -> str: + """Normalize content payload to text.""" + if isinstance(content, str): + return content.strip() + if content is None: + return "" + try: + return json.dumps(content, ensure_ascii=False) + except TypeError: + return str(content) + + +def resolve_mochat_target(raw: str) -> MochatTarget: + """Resolve id and target kind from user-provided target string.""" + trimmed = (raw or "").strip() + if not trimmed: + return MochatTarget(id="", is_panel=False) + + lowered = trimmed.lower() + cleaned, forced_panel = trimmed, False + for prefix in ("mochat:", "group:", "channel:", "panel:"): + if lowered.startswith(prefix): + cleaned = trimmed[len(prefix):].strip() + forced_panel = prefix in {"group:", "channel:", "panel:"} + break + + if not cleaned: + return MochatTarget(id="", is_panel=False) + return MochatTarget(id=cleaned, is_panel=forced_panel or not cleaned.startswith("session_")) + + +def extract_mention_ids(value: Any) -> list[str]: + """Extract mention ids from heterogeneous mention payload.""" + if not isinstance(value, list): + return [] + ids: list[str] = [] + for item in value: + if isinstance(item, str): + if item.strip(): + ids.append(item.strip()) + elif isinstance(item, dict): + for key in ("id", "userId", "_id"): + candidate = item.get(key) + if isinstance(candidate, str) and candidate.strip(): + ids.append(candidate.strip()) + break + return ids + + +def resolve_was_mentioned(payload: dict[str, Any], agent_user_id: str) -> bool: + """Resolve mention state from payload metadata and text fallback.""" + meta = payload.get("meta") + if isinstance(meta, dict): + if meta.get("mentioned") is True or meta.get("wasMentioned") is True: + return True + for f in ("mentions", "mentionIds", "mentionedUserIds", "mentionedUsers"): + if agent_user_id and agent_user_id in extract_mention_ids(meta.get(f)): + return True + if not agent_user_id: + return False + content = payload.get("content") + if not isinstance(content, str) or not content: + return False + return f"<@{agent_user_id}>" in content or f"@{agent_user_id}" in content + + +def resolve_require_mention(config: MochatConfig, session_id: str, group_id: str) -> bool: + """Resolve mention requirement for group/panel conversations.""" + groups = config.groups or {} + for key in (group_id, session_id, "*"): + if key and key in groups: + return bool(groups[key].require_mention) + return bool(config.mention.require_in_groups) + + +def build_buffered_body(entries: list[MochatBufferedEntry], is_group: bool) -> str: + """Build text body from one or more buffered entries.""" + if not entries: + return "" + if len(entries) == 1: + return entries[0].raw_body + lines: list[str] = [] + for entry in entries: + if not entry.raw_body: + continue + if is_group: + label = entry.sender_name.strip() or entry.sender_username.strip() or entry.author + if label: + lines.append(f"{label}: {entry.raw_body}") + continue + lines.append(entry.raw_body) + return "\n".join(lines).strip() + + +def parse_timestamp(value: Any) -> int | None: + """Parse event timestamp to epoch milliseconds.""" + if not isinstance(value, str) or not value.strip(): + return None + try: + return int(datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1000) + except ValueError: + return None + + +# --------------------------------------------------------------------------- +# Channel +# --------------------------------------------------------------------------- + +class MochatChannel(BaseChannel): + """Mochat channel using socket.io with fallback polling workers.""" + + name = "mochat" + + def __init__(self, config: MochatConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: MochatConfig = config + self._http: httpx.AsyncClient | None = None + self._socket: Any = None + self._ws_connected = self._ws_ready = False + + self._state_dir = get_runtime_subdir("mochat") + self._cursor_path = self._state_dir / "session_cursors.json" + self._session_cursor: dict[str, int] = {} + self._cursor_save_task: asyncio.Task | None = None + + self._session_set: set[str] = set() + self._panel_set: set[str] = set() + self._auto_discover_sessions = self._auto_discover_panels = False + + self._cold_sessions: set[str] = set() + self._session_by_converse: dict[str, str] = {} + + self._seen_set: dict[str, set[str]] = {} + self._seen_queue: dict[str, deque[str]] = {} + self._delay_states: dict[str, DelayState] = {} + + self._fallback_mode = False + self._session_fallback_tasks: dict[str, asyncio.Task] = {} + self._panel_fallback_tasks: dict[str, asyncio.Task] = {} + self._refresh_task: asyncio.Task | None = None + self._target_locks: dict[str, asyncio.Lock] = {} + + # ---- lifecycle --------------------------------------------------------- + + async def start(self) -> None: + """Start Mochat channel workers and websocket connection.""" + if not self.config.claw_token: + logger.error("Mochat claw_token not configured") + return + + self._running = True + self._http = httpx.AsyncClient(timeout=30.0) + self._state_dir.mkdir(parents=True, exist_ok=True) + await self._load_session_cursors() + self._seed_targets_from_config() + await self._refresh_targets(subscribe_new=False) + + if not await self._start_socket_client(): + await self._ensure_fallback_workers() + + self._refresh_task = asyncio.create_task(self._refresh_loop()) + while self._running: + await asyncio.sleep(1) + + async def stop(self) -> None: + """Stop all workers and clean up resources.""" + self._running = False + if self._refresh_task: + self._refresh_task.cancel() + self._refresh_task = None + + await self._stop_fallback_workers() + await self._cancel_delay_timers() + + if self._socket: + try: + await self._socket.disconnect() + except Exception: + pass + self._socket = None + + if self._cursor_save_task: + self._cursor_save_task.cancel() + self._cursor_save_task = None + await self._save_session_cursors() + + if self._http: + await self._http.aclose() + self._http = None + self._ws_connected = self._ws_ready = False + + async def send(self, msg: OutboundMessage) -> None: + """Send outbound message to session or panel.""" + if not self.config.claw_token: + logger.warning("Mochat claw_token missing, skip send") + return + + parts = ([msg.content.strip()] if msg.content and msg.content.strip() else []) + if msg.media: + parts.extend(m for m in msg.media if isinstance(m, str) and m.strip()) + content = "\n".join(parts).strip() + if not content: + return + + target = resolve_mochat_target(msg.chat_id) + if not target.id: + logger.warning("Mochat outbound target is empty") + return + + is_panel = (target.is_panel or target.id in self._panel_set) and not target.id.startswith("session_") + try: + if is_panel: + await self._api_send("/api/claw/groups/panels/send", "panelId", target.id, + content, msg.reply_to, self._read_group_id(msg.metadata)) + else: + await self._api_send("/api/claw/sessions/send", "sessionId", target.id, + content, msg.reply_to) + except Exception as e: + logger.error("Failed to send Mochat message: {}", e) + + # ---- config / init helpers --------------------------------------------- + + def _seed_targets_from_config(self) -> None: + sessions, self._auto_discover_sessions = self._normalize_id_list(self.config.sessions) + panels, self._auto_discover_panels = self._normalize_id_list(self.config.panels) + self._session_set.update(sessions) + self._panel_set.update(panels) + for sid in sessions: + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + + @staticmethod + def _normalize_id_list(values: list[str]) -> tuple[list[str], bool]: + cleaned = [str(v).strip() for v in values if str(v).strip()] + return sorted({v for v in cleaned if v != "*"}), "*" in cleaned + + # ---- websocket --------------------------------------------------------- + + async def _start_socket_client(self) -> bool: + if not SOCKETIO_AVAILABLE: + logger.warning("python-socketio not installed, Mochat using polling fallback") + return False + + serializer = "default" + if not self.config.socket_disable_msgpack: + if MSGPACK_AVAILABLE: + serializer = "msgpack" + else: + logger.warning("msgpack not installed but socket_disable_msgpack=false; using JSON") + + client = socketio.AsyncClient( + reconnection=True, + reconnection_attempts=self.config.max_retry_attempts or None, + reconnection_delay=max(0.1, self.config.socket_reconnect_delay_ms / 1000.0), + reconnection_delay_max=max(0.1, self.config.socket_max_reconnect_delay_ms / 1000.0), + logger=False, engineio_logger=False, serializer=serializer, + ) + + @client.event + async def connect() -> None: + self._ws_connected, self._ws_ready = True, False + logger.info("Mochat websocket connected") + subscribed = await self._subscribe_all() + self._ws_ready = subscribed + await (self._stop_fallback_workers() if subscribed else self._ensure_fallback_workers()) + + @client.event + async def disconnect() -> None: + if not self._running: + return + self._ws_connected = self._ws_ready = False + logger.warning("Mochat websocket disconnected") + await self._ensure_fallback_workers() + + @client.event + async def connect_error(data: Any) -> None: + logger.error("Mochat websocket connect error: {}", data) + + @client.on("claw.session.events") + async def on_session_events(payload: dict[str, Any]) -> None: + await self._handle_watch_payload(payload, "session") + + @client.on("claw.panel.events") + async def on_panel_events(payload: dict[str, Any]) -> None: + await self._handle_watch_payload(payload, "panel") + + for ev in ("notify:chat.inbox.append", "notify:chat.message.add", + "notify:chat.message.update", "notify:chat.message.recall", + "notify:chat.message.delete"): + client.on(ev, self._build_notify_handler(ev)) + + socket_url = (self.config.socket_url or self.config.base_url).strip().rstrip("/") + socket_path = (self.config.socket_path or "/socket.io").strip().lstrip("/") + + try: + self._socket = client + await client.connect( + socket_url, transports=["websocket"], socketio_path=socket_path, + auth={"token": self.config.claw_token}, + wait_timeout=max(1.0, self.config.socket_connect_timeout_ms / 1000.0), + ) + return True + except Exception as e: + logger.error("Failed to connect Mochat websocket: {}", e) + try: + await client.disconnect() + except Exception: + pass + self._socket = None + return False + + def _build_notify_handler(self, event_name: str): + async def handler(payload: Any) -> None: + if event_name == "notify:chat.inbox.append": + await self._handle_notify_inbox_append(payload) + elif event_name.startswith("notify:chat.message."): + await self._handle_notify_chat_message(payload) + return handler + + # ---- subscribe --------------------------------------------------------- + + async def _subscribe_all(self) -> bool: + ok = await self._subscribe_sessions(sorted(self._session_set)) + ok = await self._subscribe_panels(sorted(self._panel_set)) and ok + if self._auto_discover_sessions or self._auto_discover_panels: + await self._refresh_targets(subscribe_new=True) + return ok + + async def _subscribe_sessions(self, session_ids: list[str]) -> bool: + if not session_ids: + return True + for sid in session_ids: + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + + ack = await self._socket_call("com.claw.im.subscribeSessions", { + "sessionIds": session_ids, "cursors": self._session_cursor, + "limit": self.config.watch_limit, + }) + if not ack.get("result"): + logger.error("Mochat subscribeSessions failed: {}", ack.get('message', 'unknown error')) + return False + + data = ack.get("data") + items: list[dict[str, Any]] = [] + if isinstance(data, list): + items = [i for i in data if isinstance(i, dict)] + elif isinstance(data, dict): + sessions = data.get("sessions") + if isinstance(sessions, list): + items = [i for i in sessions if isinstance(i, dict)] + elif "sessionId" in data: + items = [data] + for p in items: + await self._handle_watch_payload(p, "session") + return True + + async def _subscribe_panels(self, panel_ids: list[str]) -> bool: + if not self._auto_discover_panels and not panel_ids: + return True + ack = await self._socket_call("com.claw.im.subscribePanels", {"panelIds": panel_ids}) + if not ack.get("result"): + logger.error("Mochat subscribePanels failed: {}", ack.get('message', 'unknown error')) + return False + return True + + async def _socket_call(self, event_name: str, payload: dict[str, Any]) -> dict[str, Any]: + if not self._socket: + return {"result": False, "message": "socket not connected"} + try: + raw = await self._socket.call(event_name, payload, timeout=10) + except Exception as e: + return {"result": False, "message": str(e)} + return raw if isinstance(raw, dict) else {"result": True, "data": raw} + + # ---- refresh / discovery ----------------------------------------------- + + async def _refresh_loop(self) -> None: + interval_s = max(1.0, self.config.refresh_interval_ms / 1000.0) + while self._running: + await asyncio.sleep(interval_s) + try: + await self._refresh_targets(subscribe_new=self._ws_ready) + except Exception as e: + logger.warning("Mochat refresh failed: {}", e) + if self._fallback_mode: + await self._ensure_fallback_workers() + + async def _refresh_targets(self, subscribe_new: bool) -> None: + if self._auto_discover_sessions: + await self._refresh_sessions_directory(subscribe_new) + if self._auto_discover_panels: + await self._refresh_panels(subscribe_new) + + async def _refresh_sessions_directory(self, subscribe_new: bool) -> None: + try: + response = await self._post_json("/api/claw/sessions/list", {}) + except Exception as e: + logger.warning("Mochat listSessions failed: {}", e) + return + + sessions = response.get("sessions") + if not isinstance(sessions, list): + return + + new_ids: list[str] = [] + for s in sessions: + if not isinstance(s, dict): + continue + sid = _str_field(s, "sessionId") + if not sid: + continue + if sid not in self._session_set: + self._session_set.add(sid) + new_ids.append(sid) + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + cid = _str_field(s, "converseId") + if cid: + self._session_by_converse[cid] = sid + + if not new_ids: + return + if self._ws_ready and subscribe_new: + await self._subscribe_sessions(new_ids) + if self._fallback_mode: + await self._ensure_fallback_workers() + + async def _refresh_panels(self, subscribe_new: bool) -> None: + try: + response = await self._post_json("/api/claw/groups/get", {}) + except Exception as e: + logger.warning("Mochat getWorkspaceGroup failed: {}", e) + return + + raw_panels = response.get("panels") + if not isinstance(raw_panels, list): + return + + new_ids: list[str] = [] + for p in raw_panels: + if not isinstance(p, dict): + continue + pt = p.get("type") + if isinstance(pt, int) and pt != 0: + continue + pid = _str_field(p, "id", "_id") + if pid and pid not in self._panel_set: + self._panel_set.add(pid) + new_ids.append(pid) + + if not new_ids: + return + if self._ws_ready and subscribe_new: + await self._subscribe_panels(new_ids) + if self._fallback_mode: + await self._ensure_fallback_workers() + + # ---- fallback workers -------------------------------------------------- + + async def _ensure_fallback_workers(self) -> None: + if not self._running: + return + self._fallback_mode = True + for sid in sorted(self._session_set): + t = self._session_fallback_tasks.get(sid) + if not t or t.done(): + self._session_fallback_tasks[sid] = asyncio.create_task(self._session_watch_worker(sid)) + for pid in sorted(self._panel_set): + t = self._panel_fallback_tasks.get(pid) + if not t or t.done(): + self._panel_fallback_tasks[pid] = asyncio.create_task(self._panel_poll_worker(pid)) + + async def _stop_fallback_workers(self) -> None: + self._fallback_mode = False + tasks = [*self._session_fallback_tasks.values(), *self._panel_fallback_tasks.values()] + for t in tasks: + t.cancel() + if tasks: + await asyncio.gather(*tasks, return_exceptions=True) + self._session_fallback_tasks.clear() + self._panel_fallback_tasks.clear() + + async def _session_watch_worker(self, session_id: str) -> None: + while self._running and self._fallback_mode: + try: + payload = await self._post_json("/api/claw/sessions/watch", { + "sessionId": session_id, "cursor": self._session_cursor.get(session_id, 0), + "timeoutMs": self.config.watch_timeout_ms, "limit": self.config.watch_limit, + }) + await self._handle_watch_payload(payload, "session") + except asyncio.CancelledError: + break + except Exception as e: + logger.warning("Mochat watch fallback error ({}): {}", session_id, e) + await asyncio.sleep(max(0.1, self.config.retry_delay_ms / 1000.0)) + + async def _panel_poll_worker(self, panel_id: str) -> None: + sleep_s = max(1.0, self.config.refresh_interval_ms / 1000.0) + while self._running and self._fallback_mode: + try: + resp = await self._post_json("/api/claw/groups/panels/messages", { + "panelId": panel_id, "limit": min(100, max(1, self.config.watch_limit)), + }) + msgs = resp.get("messages") + if isinstance(msgs, list): + for m in reversed(msgs): + if not isinstance(m, dict): + continue + evt = _make_synthetic_event( + message_id=str(m.get("messageId") or ""), + author=str(m.get("author") or ""), + content=m.get("content"), + meta=m.get("meta"), group_id=str(resp.get("groupId") or ""), + converse_id=panel_id, timestamp=m.get("createdAt"), + author_info=m.get("authorInfo"), + ) + await self._process_inbound_event(panel_id, evt, "panel") + except asyncio.CancelledError: + break + except Exception as e: + logger.warning("Mochat panel polling error ({}): {}", panel_id, e) + await asyncio.sleep(sleep_s) + + # ---- inbound event processing ------------------------------------------ + + async def _handle_watch_payload(self, payload: dict[str, Any], target_kind: str) -> None: + if not isinstance(payload, dict): + return + target_id = _str_field(payload, "sessionId") + if not target_id: + return + + lock = self._target_locks.setdefault(f"{target_kind}:{target_id}", asyncio.Lock()) + async with lock: + prev = self._session_cursor.get(target_id, 0) if target_kind == "session" else 0 + pc = payload.get("cursor") + if target_kind == "session" and isinstance(pc, int) and pc >= 0: + self._mark_session_cursor(target_id, pc) + + raw_events = payload.get("events") + if not isinstance(raw_events, list): + return + if target_kind == "session" and target_id in self._cold_sessions: + self._cold_sessions.discard(target_id) + return + + for event in raw_events: + if not isinstance(event, dict): + continue + seq = event.get("seq") + if target_kind == "session" and isinstance(seq, int) and seq > self._session_cursor.get(target_id, prev): + self._mark_session_cursor(target_id, seq) + if event.get("type") == "message.add": + await self._process_inbound_event(target_id, event, target_kind) + + async def _process_inbound_event(self, target_id: str, event: dict[str, Any], target_kind: str) -> None: + payload = event.get("payload") + if not isinstance(payload, dict): + return + + author = _str_field(payload, "author") + if not author or (self.config.agent_user_id and author == self.config.agent_user_id): + return + if not self.is_allowed(author): + return + + message_id = _str_field(payload, "messageId") + seen_key = f"{target_kind}:{target_id}" + if message_id and self._remember_message_id(seen_key, message_id): + return + + raw_body = normalize_mochat_content(payload.get("content")) or "[empty message]" + ai = _safe_dict(payload.get("authorInfo")) + sender_name = _str_field(ai, "nickname", "email") + sender_username = _str_field(ai, "agentId") + + group_id = _str_field(payload, "groupId") + is_group = bool(group_id) + was_mentioned = resolve_was_mentioned(payload, self.config.agent_user_id) + require_mention = target_kind == "panel" and is_group and resolve_require_mention(self.config, target_id, group_id) + use_delay = target_kind == "panel" and self.config.reply_delay_mode == "non-mention" + + if require_mention and not was_mentioned and not use_delay: + return + + entry = MochatBufferedEntry( + raw_body=raw_body, author=author, sender_name=sender_name, + sender_username=sender_username, timestamp=parse_timestamp(event.get("timestamp")), + message_id=message_id, group_id=group_id, + ) + + if use_delay: + delay_key = seen_key + if was_mentioned: + await self._flush_delayed_entries(delay_key, target_id, target_kind, "mention", entry) + else: + await self._enqueue_delayed_entry(delay_key, target_id, target_kind, entry) + return + + await self._dispatch_entries(target_id, target_kind, [entry], was_mentioned) + + # ---- dedup / buffering ------------------------------------------------- + + def _remember_message_id(self, key: str, message_id: str) -> bool: + seen_set = self._seen_set.setdefault(key, set()) + seen_queue = self._seen_queue.setdefault(key, deque()) + if message_id in seen_set: + return True + seen_set.add(message_id) + seen_queue.append(message_id) + while len(seen_queue) > MAX_SEEN_MESSAGE_IDS: + seen_set.discard(seen_queue.popleft()) + return False + + async def _enqueue_delayed_entry(self, key: str, target_id: str, target_kind: str, entry: MochatBufferedEntry) -> None: + state = self._delay_states.setdefault(key, DelayState()) + async with state.lock: + state.entries.append(entry) + if state.timer: + state.timer.cancel() + state.timer = asyncio.create_task(self._delay_flush_after(key, target_id, target_kind)) + + async def _delay_flush_after(self, key: str, target_id: str, target_kind: str) -> None: + await asyncio.sleep(max(0, self.config.reply_delay_ms) / 1000.0) + await self._flush_delayed_entries(key, target_id, target_kind, "timer", None) + + async def _flush_delayed_entries(self, key: str, target_id: str, target_kind: str, reason: str, entry: MochatBufferedEntry | None) -> None: + state = self._delay_states.setdefault(key, DelayState()) + async with state.lock: + if entry: + state.entries.append(entry) + current = asyncio.current_task() + if state.timer and state.timer is not current: + state.timer.cancel() + state.timer = None + entries = state.entries[:] + state.entries.clear() + if entries: + await self._dispatch_entries(target_id, target_kind, entries, reason == "mention") + + async def _dispatch_entries(self, target_id: str, target_kind: str, entries: list[MochatBufferedEntry], was_mentioned: bool) -> None: + if not entries: + return + last = entries[-1] + is_group = bool(last.group_id) + body = build_buffered_body(entries, is_group) or "[empty message]" + await self._handle_message( + sender_id=last.author, chat_id=target_id, content=body, + metadata={ + "message_id": last.message_id, "timestamp": last.timestamp, + "is_group": is_group, "group_id": last.group_id, + "sender_name": last.sender_name, "sender_username": last.sender_username, + "target_kind": target_kind, "was_mentioned": was_mentioned, + "buffered_count": len(entries), + }, + ) + + async def _cancel_delay_timers(self) -> None: + for state in self._delay_states.values(): + if state.timer: + state.timer.cancel() + self._delay_states.clear() + + # ---- notify handlers --------------------------------------------------- + + async def _handle_notify_chat_message(self, payload: Any) -> None: + if not isinstance(payload, dict): + return + group_id = _str_field(payload, "groupId") + panel_id = _str_field(payload, "converseId", "panelId") + if not group_id or not panel_id: + return + if self._panel_set and panel_id not in self._panel_set: + return + + evt = _make_synthetic_event( + message_id=str(payload.get("_id") or payload.get("messageId") or ""), + author=str(payload.get("author") or ""), + content=payload.get("content"), meta=payload.get("meta"), + group_id=group_id, converse_id=panel_id, + timestamp=payload.get("createdAt"), author_info=payload.get("authorInfo"), + ) + await self._process_inbound_event(panel_id, evt, "panel") + + async def _handle_notify_inbox_append(self, payload: Any) -> None: + if not isinstance(payload, dict) or payload.get("type") != "message": + return + detail = payload.get("payload") + if not isinstance(detail, dict): + return + if _str_field(detail, "groupId"): + return + converse_id = _str_field(detail, "converseId") + if not converse_id: + return + + session_id = self._session_by_converse.get(converse_id) + if not session_id: + await self._refresh_sessions_directory(self._ws_ready) + session_id = self._session_by_converse.get(converse_id) + if not session_id: + return + + evt = _make_synthetic_event( + message_id=str(detail.get("messageId") or payload.get("_id") or ""), + author=str(detail.get("messageAuthor") or ""), + content=str(detail.get("messagePlainContent") or detail.get("messageSnippet") or ""), + meta={"source": "notify:chat.inbox.append", "converseId": converse_id}, + group_id="", converse_id=converse_id, timestamp=payload.get("createdAt"), + ) + await self._process_inbound_event(session_id, evt, "session") + + # ---- cursor persistence ------------------------------------------------ + + def _mark_session_cursor(self, session_id: str, cursor: int) -> None: + if cursor < 0 or cursor < self._session_cursor.get(session_id, 0): + return + self._session_cursor[session_id] = cursor + if not self._cursor_save_task or self._cursor_save_task.done(): + self._cursor_save_task = asyncio.create_task(self._save_cursor_debounced()) + + async def _save_cursor_debounced(self) -> None: + await asyncio.sleep(CURSOR_SAVE_DEBOUNCE_S) + await self._save_session_cursors() + + async def _load_session_cursors(self) -> None: + if not self._cursor_path.exists(): + return + try: + data = json.loads(self._cursor_path.read_text("utf-8")) + except Exception as e: + logger.warning("Failed to read Mochat cursor file: {}", e) + return + cursors = data.get("cursors") if isinstance(data, dict) else None + if isinstance(cursors, dict): + for sid, cur in cursors.items(): + if isinstance(sid, str) and isinstance(cur, int) and cur >= 0: + self._session_cursor[sid] = cur + + async def _save_session_cursors(self) -> None: + try: + self._state_dir.mkdir(parents=True, exist_ok=True) + self._cursor_path.write_text(json.dumps({ + "schemaVersion": 1, "updatedAt": datetime.utcnow().isoformat(), + "cursors": self._session_cursor, + }, ensure_ascii=False, indent=2) + "\n", "utf-8") + except Exception as e: + logger.warning("Failed to save Mochat cursor file: {}", e) + + # ---- HTTP helpers ------------------------------------------------------ + + async def _post_json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]: + if not self._http: + raise RuntimeError("Mochat HTTP client not initialized") + url = f"{self.config.base_url.strip().rstrip('/')}{path}" + response = await self._http.post(url, headers={ + "Content-Type": "application/json", "X-Claw-Token": self.config.claw_token, + }, json=payload) + if not response.is_success: + raise RuntimeError(f"Mochat HTTP {response.status_code}: {response.text[:200]}") + try: + parsed = response.json() + except Exception: + parsed = response.text + if isinstance(parsed, dict) and isinstance(parsed.get("code"), int): + if parsed["code"] != 200: + msg = str(parsed.get("message") or parsed.get("name") or "request failed") + raise RuntimeError(f"Mochat API error: {msg} (code={parsed['code']})") + data = parsed.get("data") + return data if isinstance(data, dict) else {} + return parsed if isinstance(parsed, dict) else {} + + async def _api_send(self, path: str, id_key: str, id_val: str, + content: str, reply_to: str | None, group_id: str | None = None) -> dict[str, Any]: + """Unified send helper for session and panel messages.""" + body: dict[str, Any] = {id_key: id_val, "content": content} + if reply_to: + body["replyTo"] = reply_to + if group_id: + body["groupId"] = group_id + return await self._post_json(path, body) + + @staticmethod + def _read_group_id(metadata: dict[str, Any]) -> str | None: + if not isinstance(metadata, dict): + return None + value = metadata.get("group_id") or metadata.get("groupId") + return value.strip() if isinstance(value, str) and value.strip() else None diff --git a/nanobot/nanobot/channels/qq.py b/nanobot/nanobot/channels/qq.py new file mode 100644 index 0000000..5ac06e3 --- /dev/null +++ b/nanobot/nanobot/channels/qq.py @@ -0,0 +1,160 @@ +"""QQ channel implementation using botpy SDK.""" + +import asyncio +from collections import deque +from typing import TYPE_CHECKING + +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import QQConfig + +try: + import botpy + from botpy.message import C2CMessage, GroupMessage + + QQ_AVAILABLE = True +except ImportError: + QQ_AVAILABLE = False + botpy = None + C2CMessage = None + GroupMessage = None + +if TYPE_CHECKING: + from botpy.message import C2CMessage, GroupMessage + + +def _make_bot_class(channel: "QQChannel") -> "type[botpy.Client]": + """Create a botpy Client subclass bound to the given channel.""" + intents = botpy.Intents(public_messages=True, direct_message=True) + + class _Bot(botpy.Client): + def __init__(self): + # Disable botpy's file log — nanobot uses loguru; default "botpy.log" fails on read-only fs + super().__init__(intents=intents, ext_handlers=False) + + async def on_ready(self): + logger.info("QQ bot ready: {}", self.robot.name) + + async def on_c2c_message_create(self, message: "C2CMessage"): + await channel._on_message(message, is_group=False) + + async def on_group_at_message_create(self, message: "GroupMessage"): + await channel._on_message(message, is_group=True) + + async def on_direct_message_create(self, message): + await channel._on_message(message, is_group=False) + + return _Bot + + +class QQChannel(BaseChannel): + """QQ channel using botpy SDK with WebSocket connection.""" + + name = "qq" + + def __init__(self, config: QQConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: QQConfig = config + self._client: "botpy.Client | None" = None + self._processed_ids: deque = deque(maxlen=1000) + self._msg_seq: int = 1 # 消息序列号，避免被 QQ API 去重 + self._chat_type_cache: dict[str, str] = {} + + async def start(self) -> None: + """Start the QQ bot.""" + if not QQ_AVAILABLE: + logger.error("QQ SDK not installed. Run: pip install qq-botpy") + return + + if not self.config.app_id or not self.config.secret: + logger.error("QQ app_id and secret not configured") + return + + self._running = True + BotClass = _make_bot_class(self) + self._client = BotClass() + logger.info("QQ bot started (C2C & Group supported)") + await self._run_bot() + + async def _run_bot(self) -> None: + """Run the bot connection with auto-reconnect.""" + while self._running: + try: + await self._client.start(appid=self.config.app_id, secret=self.config.secret) + except Exception as e: + logger.warning("QQ bot error: {}", e) + if self._running: + logger.info("Reconnecting QQ bot in 5 seconds...") + await asyncio.sleep(5) + + async def stop(self) -> None: + """Stop the QQ bot.""" + self._running = False + if self._client: + try: + await self._client.close() + except Exception: + pass + logger.info("QQ bot stopped") + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through QQ.""" + if not self._client: + logger.warning("QQ client not initialized") + return + + try: + msg_id = msg.metadata.get("message_id") + self._msg_seq += 1 + msg_type = self._chat_type_cache.get(msg.chat_id, "c2c") + if msg_type == "group": + await self._client.api.post_group_message( + group_openid=msg.chat_id, + msg_type=2, + markdown={"content": msg.content}, + msg_id=msg_id, + msg_seq=self._msg_seq, + ) + else: + await self._client.api.post_c2c_message( + openid=msg.chat_id, + msg_type=2, + markdown={"content": msg.content}, + msg_id=msg_id, + msg_seq=self._msg_seq, + ) + except Exception as e: + logger.error("Error sending QQ message: {}", e) + + async def _on_message(self, data: "C2CMessage | GroupMessage", is_group: bool = False) -> None: + """Handle incoming message from QQ.""" + try: + # Dedup by message ID + if data.id in self._processed_ids: + return + self._processed_ids.append(data.id) + + content = (data.content or "").strip() + if not content: + return + + if is_group: + chat_id = data.group_openid + user_id = data.author.member_openid + self._chat_type_cache[chat_id] = "group" + else: + chat_id = str(getattr(data.author, 'id', None) or getattr(data.author, 'user_openid', 'unknown')) + user_id = chat_id + self._chat_type_cache[chat_id] = "c2c" + + await self._handle_message( + sender_id=user_id, + chat_id=chat_id, + content=content, + metadata={"message_id": data.id}, + ) + except Exception: + logger.exception("Error handling QQ message") diff --git a/nanobot/nanobot/channels/slack.py b/nanobot/nanobot/channels/slack.py new file mode 100644 index 0000000..a4e7324 --- /dev/null +++ b/nanobot/nanobot/channels/slack.py @@ -0,0 +1,281 @@ +"""Slack channel implementation using Socket Mode.""" + +import asyncio +import re +from typing import Any + +from loguru import logger +from slack_sdk.socket_mode.request import SocketModeRequest +from slack_sdk.socket_mode.response import SocketModeResponse +from slack_sdk.socket_mode.websockets import SocketModeClient +from slack_sdk.web.async_client import AsyncWebClient +from slackify_markdown import slackify_markdown + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import SlackConfig + + +class SlackChannel(BaseChannel): + """Slack channel using Socket Mode.""" + + name = "slack" + + def __init__(self, config: SlackConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: SlackConfig = config + self._web_client: AsyncWebClient | None = None + self._socket_client: SocketModeClient | None = None + self._bot_user_id: str | None = None + + async def start(self) -> None: + """Start the Slack Socket Mode client.""" + if not self.config.bot_token or not self.config.app_token: + logger.error("Slack bot/app token not configured") + return + if self.config.mode != "socket": + logger.error("Unsupported Slack mode: {}", self.config.mode) + return + + self._running = True + + self._web_client = AsyncWebClient(token=self.config.bot_token) + self._socket_client = SocketModeClient( + app_token=self.config.app_token, + web_client=self._web_client, + ) + + self._socket_client.socket_mode_request_listeners.append(self._on_socket_request) + + # Resolve bot user ID for mention handling + try: + auth = await self._web_client.auth_test() + self._bot_user_id = auth.get("user_id") + logger.info("Slack bot connected as {}", self._bot_user_id) + except Exception as e: + logger.warning("Slack auth_test failed: {}", e) + + logger.info("Starting Slack Socket Mode client...") + await self._socket_client.connect() + + while self._running: + await asyncio.sleep(1) + + async def stop(self) -> None: + """Stop the Slack client.""" + self._running = False + if self._socket_client: + try: + await self._socket_client.close() + except Exception as e: + logger.warning("Slack socket close failed: {}", e) + self._socket_client = None + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through Slack.""" + if not self._web_client: + logger.warning("Slack client not running") + return + try: + slack_meta = msg.metadata.get("slack", {}) if msg.metadata else {} + thread_ts = slack_meta.get("thread_ts") + channel_type = slack_meta.get("channel_type") + # Only reply in thread for channel/group messages; DMs don't use threads + thread_ts_param = thread_ts if use_thread else None + + # Slack rejects empty text payloads. Keep media-only messages media-only, + # but send a single blank message when the bot has no text or files to send. + if msg.content or not (msg.media or []): + await self._web_client.chat_postMessage( + channel=msg.chat_id, + text=self._to_mrkdwn(msg.content) if msg.content else " ", + thread_ts=thread_ts_param, + ) + + for media_path in msg.media or []: + try: + await self._web_client.files_upload_v2( + channel=msg.chat_id, + file=media_path, + thread_ts=thread_ts_param, + ) + except Exception as e: + logger.error("Failed to upload file {}: {}", media_path, e) + except Exception as e: + logger.error("Error sending Slack message: {}", e) + + async def _on_socket_request( + self, + client: SocketModeClient, + req: SocketModeRequest, + ) -> None: + """Handle incoming Socket Mode requests.""" + if req.type != "events_api": + return + + # Acknowledge right away + await client.send_socket_mode_response( + SocketModeResponse(envelope_id=req.envelope_id) + ) + + payload = req.payload or {} + event = payload.get("event") or {} + event_type = event.get("type") + + # Handle app mentions or plain messages + if event_type not in ("message", "app_mention"): + return + + sender_id = event.get("user") + chat_id = event.get("channel") + + # Ignore bot/system messages (any subtype = not a normal user message) + if event.get("subtype"): + return + if self._bot_user_id and sender_id == self._bot_user_id: + return + + # Avoid double-processing: Slack sends both `message` and `app_mention` + # for mentions in channels. Prefer `app_mention`. + text = event.get("text") or "" + if event_type == "message" and self._bot_user_id and f"<@{self._bot_user_id}>" in text: + return + + # Debug: log basic event shape + logger.debug( + "Slack event: type={} subtype={} user={} channel={} channel_type={} text={}", + event_type, + event.get("subtype"), + sender_id, + chat_id, + event.get("channel_type"), + text[:80], + ) + if not sender_id or not chat_id: + return + + channel_type = event.get("channel_type") or "" + + if not self._is_allowed(sender_id, chat_id, channel_type): + return + + if channel_type != "im" and not self._should_respond_in_channel(event_type, text, chat_id): + return + + text = self._strip_bot_mention(text) + + thread_ts = event.get("thread_ts") + if self.config.reply_in_thread and not thread_ts: + thread_ts = event.get("ts") + # Add :eyes: reaction to the triggering message (best-effort) + try: + if self._web_client and event.get("ts"): + await self._web_client.reactions_add( + channel=chat_id, + name=self.config.react_emoji, + timestamp=event.get("ts"), + ) + except Exception as e: + logger.debug("Slack reactions_add failed: {}", e) + + # Thread-scoped session key for channel/group messages + session_key = f"slack:{chat_id}:{thread_ts}" if thread_ts and channel_type != "im" else None + + try: + await self._handle_message( + sender_id=sender_id, + chat_id=chat_id, + content=text, + metadata={ + "slack": { + "event": event, + "thread_ts": thread_ts, + "channel_type": channel_type, + }, + }, + session_key=session_key, + ) + except Exception: + logger.exception("Error handling Slack message from {}", sender_id) + + def _is_allowed(self, sender_id: str, chat_id: str, channel_type: str) -> bool: + if channel_type == "im": + if not self.config.dm.enabled: + return False + if self.config.dm.policy == "allowlist": + return sender_id in self.config.dm.allow_from + return True + + # Group / channel messages + if self.config.group_policy == "allowlist": + return chat_id in self.config.group_allow_from + return True + + def _should_respond_in_channel(self, event_type: str, text: str, chat_id: str) -> bool: + if self.config.group_policy == "open": + return True + if self.config.group_policy == "mention": + if event_type == "app_mention": + return True + return self._bot_user_id is not None and f"<@{self._bot_user_id}>" in text + if self.config.group_policy == "allowlist": + return chat_id in self.config.group_allow_from + return False + + def _strip_bot_mention(self, text: str) -> str: + if not text or not self._bot_user_id: + return text + return re.sub(rf"<@{re.escape(self._bot_user_id)}>\s*", "", text).strip() + + _TABLE_RE = re.compile(r"(?m)^\|.*\|$(?:\n\|[\s:|-]*\|$)(?:\n\|.*\|$)*") + _CODE_FENCE_RE = re.compile(r"```[\s\S]*?```") + _INLINE_CODE_RE = re.compile(r"`[^`]+`") + _LEFTOVER_BOLD_RE = re.compile(r"\*\*(.+?)\*\*") + _LEFTOVER_HEADER_RE = re.compile(r"^#{1,6}\s+(.+)$", re.MULTILINE) + _BARE_URL_RE = re.compile(r"(? str: + """Convert Markdown to Slack mrkdwn, including tables.""" + if not text: + return "" + text = cls._TABLE_RE.sub(cls._convert_table, text) + return cls._fixup_mrkdwn(slackify_markdown(text)) + + @classmethod + def _fixup_mrkdwn(cls, text: str) -> str: + """Fix markdown artifacts that slackify_markdown misses.""" + code_blocks: list[str] = [] + + def _save_code(m: re.Match) -> str: + code_blocks.append(m.group(0)) + return f"\x00CB{len(code_blocks) - 1}\x00" + + text = cls._CODE_FENCE_RE.sub(_save_code, text) + text = cls._INLINE_CODE_RE.sub(_save_code, text) + text = cls._LEFTOVER_BOLD_RE.sub(r"*\1*", text) + text = cls._LEFTOVER_HEADER_RE.sub(r"*\1*", text) + text = cls._BARE_URL_RE.sub(lambda m: m.group(0).replace("&", "&"), text) + + for i, block in enumerate(code_blocks): + text = text.replace(f"\x00CB{i}\x00", block) + return text + + @staticmethod + def _convert_table(match: re.Match) -> str: + """Convert a Markdown table to a Slack-readable list.""" + lines = [ln.strip() for ln in match.group(0).strip().splitlines() if ln.strip()] + if len(lines) < 2: + return match.group(0) + headers = [h.strip() for h in lines[0].strip("|").split("|")] + start = 2 if re.fullmatch(r"[|\s:\-]+", lines[1]) else 1 + rows: list[str] = [] + for line in lines[start:]: + cells = [c.strip() for c in line.strip("|").split("|")] + cells = (cells + [""] * len(headers))[: len(headers)] + parts = [f"**{headers[i]}**: {cells[i]}" for i in range(len(headers)) if cells[i]] + if parts: + rows.append(" · ".join(parts)) + return "\n".join(rows) + diff --git a/nanobot/nanobot/channels/telegram.py b/nanobot/nanobot/channels/telegram.py new file mode 100644 index 0000000..ecb1440 --- /dev/null +++ b/nanobot/nanobot/channels/telegram.py @@ -0,0 +1,672 @@ +"""Telegram channel implementation using python-telegram-bot.""" + +from __future__ import annotations + +import asyncio +import re +import time +import unicodedata + +from loguru import logger +from telegram import BotCommand, ReplyParameters, Update +from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters +from telegram.request import HTTPXRequest + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_media_dir +from nanobot.config.schema import TelegramConfig +from nanobot.utils.helpers import split_message + +TELEGRAM_MAX_MESSAGE_LEN = 4000 # Telegram message character limit + + +def _strip_md(s: str) -> str: + """Strip markdown inline formatting from text.""" + s = re.sub(r'\*\*(.+?)\*\*', r'\1', s) + s = re.sub(r'__(.+?)__', r'\1', s) + s = re.sub(r'~~(.+?)~~', r'\1', s) + s = re.sub(r'`([^`]+)`', r'\1', s) + return s.strip() + + +def _render_table_box(table_lines: list[str]) -> str: + """Convert markdown pipe-table to compact aligned text for
display."""
+
+ def dw(s: str) -> int:
+ return sum(2 if unicodedata.east_asian_width(c) in ('W', 'F') else 1 for c in s)
+
+ rows: list[list[str]] = []
+ has_sep = False
+ for line in table_lines:
+ cells = [_strip_md(c) for c in line.strip().strip('|').split('|')]
+ if all(re.match(r'^:?-+:?$', c) for c in cells if c):
+ has_sep = True
+ continue
+ rows.append(cells)
+ if not rows or not has_sep:
+ return '\n'.join(table_lines)
+
+ ncols = max(len(r) for r in rows)
+ for r in rows:
+ r.extend([''] * (ncols - len(r)))
+ widths = [max(dw(r[c]) for r in rows) for c in range(ncols)]
+
+ def dr(cells: list[str]) -> str:
+ return ' '.join(f'{c}{" " * (w - dw(c))}' for c, w in zip(cells, widths))
+
+ out = [dr(rows[0])]
+ out.append(' '.join('─' * w for w in widths))
+ for row in rows[1:]:
+ out.append(dr(row))
+ return '\n'.join(out)
+
+
+def _markdown_to_telegram_html(text: str) -> str:
+ """
+ Convert markdown to Telegram-safe HTML.
+ """
+ if not text:
+ return ""
+
+ # 1. Extract and protect code blocks (preserve content from other processing)
+ code_blocks: list[str] = []
+ def save_code_block(m: re.Match) -> str:
+ code_blocks.append(m.group(1))
+ return f"\x00CB{len(code_blocks) - 1}\x00"
+
+ text = re.sub(r'```[\w]*\n?([\s\S]*?)```', save_code_block, text)
+
+ # 1.5. Convert markdown tables to box-drawing (reuse code_block placeholders)
+ lines = text.split('\n')
+ rebuilt: list[str] = []
+ li = 0
+ while li < len(lines):
+ if re.match(r'^\s*\|.+\|', lines[li]):
+ tbl: list[str] = []
+ while li < len(lines) and re.match(r'^\s*\|.+\|', lines[li]):
+ tbl.append(lines[li])
+ li += 1
+ box = _render_table_box(tbl)
+ if box != '\n'.join(tbl):
+ code_blocks.append(box)
+ rebuilt.append(f"\x00CB{len(code_blocks) - 1}\x00")
+ else:
+ rebuilt.extend(tbl)
+ else:
+ rebuilt.append(lines[li])
+ li += 1
+ text = '\n'.join(rebuilt)
+
+ # 2. Extract and protect inline code
+ inline_codes: list[str] = []
+ def save_inline_code(m: re.Match) -> str:
+ inline_codes.append(m.group(1))
+ return f"\x00IC{len(inline_codes) - 1}\x00"
+
+ text = re.sub(r'`([^`]+)`', save_inline_code, text)
+
+ # 3. Headers # Title -> just the title text
+ text = re.sub(r'^#{1,6}\s+(.+)$', r'\1', text, flags=re.MULTILINE)
+
+ # 4. Blockquotes > text -> just the text (before HTML escaping)
+ text = re.sub(r'^>\s*(.*)$', r'\1', text, flags=re.MULTILINE)
+
+ # 5. Escape HTML special characters
+ text = text.replace("&", "&").replace("<", "<").replace(">", ">")
+
+ # 6. Links [text](url) - must be before bold/italic to handle nested cases
+ text = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'\1', text)
+
+ # 7. Bold **text** or __text__
+ text = re.sub(r'\*\*(.+?)\*\*', r'\1', text)
+ text = re.sub(r'__(.+?)__', r'\1', text)
+
+ # 8. Italic _text_ (avoid matching inside words like some_var_name)
+ text = re.sub(r'(?\1', text)
+
+ # 9. Strikethrough ~~text~~
+ text = re.sub(r'~~(.+?)~~', r'\1', text)
+
+ # 10. Bullet lists - item -> • item
+ text = re.sub(r'^[-*]\s+', '• ', text, flags=re.MULTILINE)
+
+ # 11. Restore inline code with HTML tags
+ for i, code in enumerate(inline_codes):
+ # Escape HTML in code content
+ escaped = code.replace("&", "&").replace("<", "<").replace(">", ">")
+ text = text.replace(f"\x00IC{i}\x00", f"{escaped}")
+
+ # 12. Restore code blocks with HTML tags
+ for i, code in enumerate(code_blocks):
+ # Escape HTML in code content
+ escaped = code.replace("&", "&").replace("<", "<").replace(">", ">")
+ text = text.replace(f"\x00CB{i}\x00", f"{escaped}
")
+
+ return text
+
+
+class TelegramChannel(BaseChannel):
+ """
+ Telegram channel using long polling.
+
+ Simple and reliable - no webhook/public IP needed.
+ """
+
+ name = "telegram"
+
+ # Commands registered with Telegram's command menu
+ BOT_COMMANDS = [
+ BotCommand("start", "Start the bot"),
+ BotCommand("new", "Start a new conversation"),
+ BotCommand("stop", "Stop the current task"),
+ BotCommand("help", "Show available commands"),
+ ]
+
+ def __init__(
+ self,
+ config: TelegramConfig,
+ bus: MessageBus,
+ groq_api_key: str = "",
+ ):
+ super().__init__(config, bus)
+ self.config: TelegramConfig = config
+ self.groq_api_key = groq_api_key
+ self._app: Application | None = None
+ self._chat_ids: dict[str, int] = {} # Map sender_id to chat_id for replies
+ self._typing_tasks: dict[str, asyncio.Task] = {} # chat_id -> typing loop task
+ self._media_group_buffers: dict[str, dict] = {}
+ self._media_group_tasks: dict[str, asyncio.Task] = {}
+ self._message_threads: dict[tuple[str, int], int] = {}
+
+ def is_allowed(self, sender_id: str) -> bool:
+ """Preserve Telegram's legacy id|username allowlist matching."""
+ if super().is_allowed(sender_id):
+ return True
+
+ allow_list = getattr(self.config, "allow_from", [])
+ if not allow_list or "*" in allow_list:
+ return False
+
+ sender_str = str(sender_id)
+ if sender_str.count("|") != 1:
+ return False
+
+ sid, username = sender_str.split("|", 1)
+ if not sid.isdigit() or not username:
+ return False
+
+ return sid in allow_list or username in allow_list
+
+ async def start(self) -> None:
+ """Start the Telegram bot with long polling."""
+ if not self.config.token:
+ logger.error("Telegram bot token not configured")
+ return
+
+ self._running = True
+
+ # Build the application with larger connection pool to avoid pool-timeout on long runs
+ req = HTTPXRequest(
+ connection_pool_size=16,
+ pool_timeout=5.0,
+ connect_timeout=30.0,
+ read_timeout=30.0,
+ proxy=self.config.proxy if self.config.proxy else None,
+ )
+ builder = Application.builder().token(self.config.token).request(req).get_updates_request(req)
+ self._app = builder.build()
+ self._app.add_error_handler(self._on_error)
+
+ # Add command handlers
+ self._app.add_handler(CommandHandler("start", self._on_start))
+ self._app.add_handler(CommandHandler("new", self._forward_command))
+ self._app.add_handler(CommandHandler("stop", self._forward_command))
+ self._app.add_handler(CommandHandler("help", self._on_help))
+
+ # Add message handler for text, photos, voice, documents
+ self._app.add_handler(
+ MessageHandler(
+ (filters.TEXT | filters.PHOTO | filters.VOICE | filters.AUDIO | filters.Document.ALL)
+ & ~filters.COMMAND,
+ self._on_message
+ )
+ )
+
+ logger.info("Starting Telegram bot (polling mode)...")
+
+ # Initialize and start polling
+ await self._app.initialize()
+ await self._app.start()
+
+ # Get bot info and register command menu
+ bot_info = await self._app.bot.get_me()
+ logger.info("Telegram bot @{} connected", bot_info.username)
+
+ try:
+ await self._app.bot.set_my_commands(self.BOT_COMMANDS)
+ logger.debug("Telegram bot commands registered")
+ except Exception as e:
+ logger.warning("Failed to register bot commands: {}", e)
+
+ # Start polling (this runs until stopped)
+ await self._app.updater.start_polling(
+ allowed_updates=["message"],
+ drop_pending_updates=True # Ignore old messages on startup
+ )
+
+ # Keep running until stopped
+ while self._running:
+ await asyncio.sleep(1)
+
+ async def stop(self) -> None:
+ """Stop the Telegram bot."""
+ self._running = False
+
+ # Cancel all typing indicators
+ for chat_id in list(self._typing_tasks):
+ self._stop_typing(chat_id)
+
+ for task in self._media_group_tasks.values():
+ task.cancel()
+ self._media_group_tasks.clear()
+ self._media_group_buffers.clear()
+
+ if self._app:
+ logger.info("Stopping Telegram bot...")
+ await self._app.updater.stop()
+ await self._app.stop()
+ await self._app.shutdown()
+ self._app = None
+
+ @staticmethod
+ def _get_media_type(path: str) -> str:
+ """Guess media type from file extension."""
+ ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
+ if ext in ("jpg", "jpeg", "png", "gif", "webp"):
+ return "photo"
+ if ext == "ogg":
+ return "voice"
+ if ext in ("mp3", "m4a", "wav", "aac"):
+ return "audio"
+ return "document"
+
+ async def send(self, msg: OutboundMessage) -> None:
+ """Send a message through Telegram."""
+ if not self._app:
+ logger.warning("Telegram bot not running")
+ return
+
+ # Only stop typing indicator for final responses
+ if not msg.metadata.get("_progress", False):
+ self._stop_typing(msg.chat_id)
+
+ try:
+ chat_id = int(msg.chat_id)
+ except ValueError:
+ logger.error("Invalid chat_id: {}", msg.chat_id)
+ return
+ reply_to_message_id = msg.metadata.get("message_id")
+ message_thread_id = msg.metadata.get("message_thread_id")
+ if message_thread_id is None and reply_to_message_id is not None:
+ message_thread_id = self._message_threads.get((msg.chat_id, reply_to_message_id))
+ thread_kwargs = {}
+ if message_thread_id is not None:
+ thread_kwargs["message_thread_id"] = message_thread_id
+
+ reply_params = None
+ if self.config.reply_to_message:
+ if reply_to_message_id:
+ reply_params = ReplyParameters(
+ message_id=reply_to_message_id,
+ allow_sending_without_reply=True
+ )
+
+ # Send media files
+ for media_path in (msg.media or []):
+ try:
+ media_type = self._get_media_type(media_path)
+ sender = {
+ "photo": self._app.bot.send_photo,
+ "voice": self._app.bot.send_voice,
+ "audio": self._app.bot.send_audio,
+ }.get(media_type, self._app.bot.send_document)
+ param = "photo" if media_type == "photo" else media_type if media_type in ("voice", "audio") else "document"
+ with open(media_path, 'rb') as f:
+ await sender(
+ chat_id=chat_id,
+ **{param: f},
+ reply_parameters=reply_params,
+ **thread_kwargs,
+ )
+ except Exception as e:
+ filename = media_path.rsplit("/", 1)[-1]
+ logger.error("Failed to send media {}: {}", media_path, e)
+ await self._app.bot.send_message(
+ chat_id=chat_id,
+ text=f"[Failed to send: {filename}]",
+ reply_parameters=reply_params,
+ **thread_kwargs,
+ )
+
+ # Send text content
+ if msg.content and msg.content != "[empty message]":
+ is_progress = msg.metadata.get("_progress", False)
+
+ for chunk in split_message(msg.content, TELEGRAM_MAX_MESSAGE_LEN):
+ # Final response: simulate streaming via draft, then persist
+ if not is_progress:
+ await self._send_with_streaming(chat_id, chunk, reply_params, thread_kwargs)
+ else:
+ await self._send_text(chat_id, chunk, reply_params, thread_kwargs)
+
+ async def _send_text(
+ self,
+ chat_id: int,
+ text: str,
+ reply_params=None,
+ thread_kwargs: dict | None = None,
+ ) -> None:
+ """Send a plain text message with HTML fallback."""
+ try:
+ html = _markdown_to_telegram_html(text)
+ await self._app.bot.send_message(
+ chat_id=chat_id, text=html, parse_mode="HTML",
+ reply_parameters=reply_params,
+ **(thread_kwargs or {}),
+ )
+ except Exception as e:
+ logger.warning("HTML parse failed, falling back to plain text: {}", e)
+ try:
+ await self._app.bot.send_message(
+ chat_id=chat_id,
+ text=text,
+ reply_parameters=reply_params,
+ **(thread_kwargs or {}),
+ )
+ except Exception as e2:
+ logger.error("Error sending Telegram message: {}", e2)
+
+ async def _send_with_streaming(
+ self,
+ chat_id: int,
+ text: str,
+ reply_params=None,
+ thread_kwargs: dict | None = None,
+ ) -> None:
+ """Simulate streaming via send_message_draft, then persist with send_message."""
+ draft_id = int(time.time() * 1000) % (2**31)
+ try:
+ step = max(len(text) // 8, 40)
+ for i in range(step, len(text), step):
+ await self._app.bot.send_message_draft(
+ chat_id=chat_id, draft_id=draft_id, text=text[:i],
+ )
+ await asyncio.sleep(0.04)
+ await self._app.bot.send_message_draft(
+ chat_id=chat_id, draft_id=draft_id, text=text,
+ )
+ await asyncio.sleep(0.15)
+ except Exception:
+ pass
+ await self._send_text(chat_id, text, reply_params, thread_kwargs)
+
+ async def _on_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+ """Handle /start command."""
+ if not update.message or not update.effective_user:
+ return
+
+ user = update.effective_user
+ await update.message.reply_text(
+ f"👋 Hi {user.first_name}! I'm nanobot.\n\n"
+ "Send me a message and I'll respond!\n"
+ "Type /help to see available commands."
+ )
+
+ async def _on_help(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+ """Handle /help command, bypassing ACL so all users can access it."""
+ if not update.message:
+ return
+ await update.message.reply_text(
+ "🐈 nanobot commands:\n"
+ "/new — Start a new conversation\n"
+ "/stop — Stop the current task\n"
+ "/help — Show available commands"
+ )
+
+ @staticmethod
+ def _sender_id(user) -> str:
+ """Build sender_id with username for allowlist matching."""
+ sid = str(user.id)
+ return f"{sid}|{user.username}" if user.username else sid
+
+ @staticmethod
+ def _derive_topic_session_key(message) -> str | None:
+ """Derive topic-scoped session key for non-private Telegram chats."""
+ message_thread_id = getattr(message, "message_thread_id", None)
+ if message.chat.type == "private" or message_thread_id is None:
+ return None
+ return f"telegram:{message.chat_id}:topic:{message_thread_id}"
+
+ @staticmethod
+ def _build_message_metadata(message, user) -> dict:
+ """Build common Telegram inbound metadata payload."""
+ return {
+ "message_id": message.message_id,
+ "user_id": user.id,
+ "username": user.username,
+ "first_name": user.first_name,
+ "is_group": message.chat.type != "private",
+ "message_thread_id": getattr(message, "message_thread_id", None),
+ "is_forum": bool(getattr(message.chat, "is_forum", False)),
+ }
+
+ def _remember_thread_context(self, message) -> None:
+ """Cache topic thread id by chat/message id for follow-up replies."""
+ message_thread_id = getattr(message, "message_thread_id", None)
+ if message_thread_id is None:
+ return
+ key = (str(message.chat_id), message.message_id)
+ self._message_threads[key] = message_thread_id
+ if len(self._message_threads) > 1000:
+ self._message_threads.pop(next(iter(self._message_threads)))
+
+ async def _forward_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+ """Forward slash commands to the bus for unified handling in AgentLoop."""
+ if not update.message or not update.effective_user:
+ return
+ message = update.message
+ user = update.effective_user
+ self._remember_thread_context(message)
+ await self._handle_message(
+ sender_id=self._sender_id(user),
+ chat_id=str(message.chat_id),
+ content=message.text,
+ metadata=self._build_message_metadata(message, user),
+ session_key=self._derive_topic_session_key(message),
+ )
+
+ async def _on_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+ """Handle incoming messages (text, photos, voice, documents)."""
+ if not update.message or not update.effective_user:
+ return
+
+ message = update.message
+ user = update.effective_user
+ chat_id = message.chat_id
+ sender_id = self._sender_id(user)
+ self._remember_thread_context(message)
+
+ # Store chat_id for replies
+ self._chat_ids[sender_id] = chat_id
+
+ # Build content from text and/or media
+ content_parts = []
+ media_paths = []
+
+ # Text content
+ if message.text:
+ content_parts.append(message.text)
+ if message.caption:
+ content_parts.append(message.caption)
+
+ # Handle media files
+ media_file = None
+ media_type = None
+
+ if message.photo:
+ media_file = message.photo[-1] # Largest photo
+ media_type = "image"
+ elif message.voice:
+ media_file = message.voice
+ media_type = "voice"
+ elif message.audio:
+ media_file = message.audio
+ media_type = "audio"
+ elif message.document:
+ media_file = message.document
+ media_type = "file"
+
+ # Download media if present
+ if media_file and self._app:
+ try:
+ file = await self._app.bot.get_file(media_file.file_id)
+ ext = self._get_extension(
+ media_type,
+ getattr(media_file, 'mime_type', None),
+ getattr(media_file, 'file_name', None),
+ )
+ media_dir = get_media_dir("telegram")
+
+ file_path = media_dir / f"{media_file.file_id[:16]}{ext}"
+ await file.download_to_drive(str(file_path))
+
+ media_paths.append(str(file_path))
+
+ # Handle voice transcription
+ if media_type == "voice" or media_type == "audio":
+ from nanobot.providers.transcription import GroqTranscriptionProvider
+ transcriber = GroqTranscriptionProvider(api_key=self.groq_api_key)
+ transcription = await transcriber.transcribe(file_path)
+ if transcription:
+ logger.info("Transcribed {}: {}...", media_type, transcription[:50])
+ content_parts.append(f"[transcription: {transcription}]")
+ else:
+ content_parts.append(f"[{media_type}: {file_path}]")
+ else:
+ content_parts.append(f"[{media_type}: {file_path}]")
+
+ logger.debug("Downloaded {} to {}", media_type, file_path)
+ except Exception as e:
+ logger.error("Failed to download media: {}", e)
+ content_parts.append(f"[{media_type}: download failed]")
+
+ content = "\n".join(content_parts) if content_parts else "[empty message]"
+
+ logger.debug("Telegram message from {}: {}...", sender_id, content[:50])
+
+ str_chat_id = str(chat_id)
+ metadata = self._build_message_metadata(message, user)
+ session_key = self._derive_topic_session_key(message)
+
+ # Telegram media groups: buffer briefly, forward as one aggregated turn.
+ if media_group_id := getattr(message, "media_group_id", None):
+ key = f"{str_chat_id}:{media_group_id}"
+ if key not in self._media_group_buffers:
+ self._media_group_buffers[key] = {
+ "sender_id": sender_id, "chat_id": str_chat_id,
+ "contents": [], "media": [],
+ "metadata": metadata,
+ "session_key": session_key,
+ }
+ self._start_typing(str_chat_id)
+ buf = self._media_group_buffers[key]
+ if content and content != "[empty message]":
+ buf["contents"].append(content)
+ buf["media"].extend(media_paths)
+ if key not in self._media_group_tasks:
+ self._media_group_tasks[key] = asyncio.create_task(self._flush_media_group(key))
+ return
+
+ # Start typing indicator before processing
+ self._start_typing(str_chat_id)
+
+ # Forward to the message bus
+ await self._handle_message(
+ sender_id=sender_id,
+ chat_id=str_chat_id,
+ content=content,
+ media=media_paths,
+ metadata=metadata,
+ session_key=session_key,
+ )
+
+ async def _flush_media_group(self, key: str) -> None:
+ """Wait briefly, then forward buffered media-group as one turn."""
+ try:
+ await asyncio.sleep(0.6)
+ if not (buf := self._media_group_buffers.pop(key, None)):
+ return
+ content = "\n".join(buf["contents"]) or "[empty message]"
+ await self._handle_message(
+ sender_id=buf["sender_id"], chat_id=buf["chat_id"],
+ content=content, media=list(dict.fromkeys(buf["media"])),
+ metadata=buf["metadata"],
+ session_key=buf.get("session_key"),
+ )
+ finally:
+ self._media_group_tasks.pop(key, None)
+
+ def _start_typing(self, chat_id: str) -> None:
+ """Start sending 'typing...' indicator for a chat."""
+ # Cancel any existing typing task for this chat
+ self._stop_typing(chat_id)
+ self._typing_tasks[chat_id] = asyncio.create_task(self._typing_loop(chat_id))
+
+ def _stop_typing(self, chat_id: str) -> None:
+ """Stop the typing indicator for a chat."""
+ task = self._typing_tasks.pop(chat_id, None)
+ if task and not task.done():
+ task.cancel()
+
+ async def _typing_loop(self, chat_id: str) -> None:
+ """Repeatedly send 'typing' action until cancelled."""
+ try:
+ while self._app:
+ await self._app.bot.send_chat_action(chat_id=int(chat_id), action="typing")
+ await asyncio.sleep(4)
+ except asyncio.CancelledError:
+ pass
+ except Exception as e:
+ logger.debug("Typing indicator stopped for {}: {}", chat_id, e)
+
+ async def _on_error(self, update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
+ """Log polling / handler errors instead of silently swallowing them."""
+ logger.error("Telegram error: {}", context.error)
+
+ def _get_extension(
+ self,
+ media_type: str,
+ mime_type: str | None,
+ filename: str | None = None,
+ ) -> str:
+ """Get file extension based on media type or original filename."""
+ if mime_type:
+ ext_map = {
+ "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif",
+ "audio/ogg": ".ogg", "audio/mpeg": ".mp3", "audio/mp4": ".m4a",
+ }
+ if mime_type in ext_map:
+ return ext_map[mime_type]
+
+ type_map = {"image": ".jpg", "voice": ".ogg", "audio": ".mp3", "file": ""}
+ if ext := type_map.get(media_type, ""):
+ return ext
+
+ if filename:
+ from pathlib import Path
+
+ return "".join(Path(filename).suffixes)
+
+ return ""
diff --git a/nanobot/nanobot/channels/whatsapp.py b/nanobot/nanobot/channels/whatsapp.py
new file mode 100644
index 0000000..1307716
--- /dev/null
+++ b/nanobot/nanobot/channels/whatsapp.py
@@ -0,0 +1,170 @@
+"""WhatsApp channel implementation using Node.js bridge."""
+
+import asyncio
+import json
+import mimetypes
+from collections import OrderedDict
+
+from loguru import logger
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+from nanobot.config.schema import WhatsAppConfig
+
+
+class WhatsAppChannel(BaseChannel):
+ """
+ WhatsApp channel that connects to a Node.js bridge.
+
+ The bridge uses @whiskeysockets/baileys to handle the WhatsApp Web protocol.
+ Communication between Python and Node.js is via WebSocket.
+ """
+
+ name = "whatsapp"
+
+ def __init__(self, config: WhatsAppConfig, bus: MessageBus):
+ super().__init__(config, bus)
+ self.config: WhatsAppConfig = config
+ self._ws = None
+ self._connected = False
+ self._processed_message_ids: OrderedDict[str, None] = OrderedDict()
+
+ async def start(self) -> None:
+ """Start the WhatsApp channel by connecting to the bridge."""
+ import websockets
+
+ bridge_url = self.config.bridge_url
+
+ logger.info("Connecting to WhatsApp bridge at {}...", bridge_url)
+
+ self._running = True
+
+ while self._running:
+ try:
+ async with websockets.connect(bridge_url) as ws:
+ self._ws = ws
+ # Send auth token if configured
+ if self.config.bridge_token:
+ await ws.send(json.dumps({"type": "auth", "token": self.config.bridge_token}))
+ self._connected = True
+ logger.info("Connected to WhatsApp bridge")
+
+ # Listen for messages
+ async for message in ws:
+ try:
+ await self._handle_bridge_message(message)
+ except Exception as e:
+ logger.error("Error handling bridge message: {}", e)
+
+ except asyncio.CancelledError:
+ break
+ except Exception as e:
+ self._connected = False
+ self._ws = None
+ logger.warning("WhatsApp bridge connection error: {}", e)
+
+ if self._running:
+ logger.info("Reconnecting in 5 seconds...")
+ await asyncio.sleep(5)
+
+ async def stop(self) -> None:
+ """Stop the WhatsApp channel."""
+ self._running = False
+ self._connected = False
+
+ if self._ws:
+ await self._ws.close()
+ self._ws = None
+
+ async def send(self, msg: OutboundMessage) -> None:
+ """Send a message through WhatsApp."""
+ if not self._ws or not self._connected:
+ logger.warning("WhatsApp bridge not connected")
+ return
+
+ try:
+ payload = {
+ "type": "send",
+ "to": msg.chat_id,
+ "text": msg.content
+ }
+ await self._ws.send(json.dumps(payload, ensure_ascii=False))
+ except Exception as e:
+ logger.error("Error sending WhatsApp message: {}", e)
+
+ async def _handle_bridge_message(self, raw: str) -> None:
+ """Handle a message from the bridge."""
+ try:
+ data = json.loads(raw)
+ except json.JSONDecodeError:
+ logger.warning("Invalid JSON from bridge: {}", raw[:100])
+ return
+
+ msg_type = data.get("type")
+
+ if msg_type == "message":
+ # Incoming message from WhatsApp
+ # Deprecated by whatsapp: old phone number style typically: @s.whatspp.net
+ pn = data.get("pn", "")
+ # New LID sytle typically:
+ sender = data.get("sender", "")
+ content = data.get("content", "")
+ message_id = data.get("id", "")
+
+ if message_id:
+ if message_id in self._processed_message_ids:
+ return
+ self._processed_message_ids[message_id] = None
+ while len(self._processed_message_ids) > 1000:
+ self._processed_message_ids.popitem(last=False)
+
+ # Extract just the phone number or lid as chat_id
+ user_id = pn if pn else sender
+ sender_id = user_id.split("@")[0] if "@" in user_id else user_id
+ logger.info("Sender {}", sender)
+
+ # Handle voice transcription if it's a voice message
+ if content == "[Voice Message]":
+ logger.info("Voice message received from {}, but direct download from bridge is not yet supported.", sender_id)
+ content = "[Voice Message: Transcription not available for WhatsApp yet]"
+
+ # Extract media paths (images/documents/videos downloaded by the bridge)
+ media_paths = data.get("media") or []
+
+ # Build content tags matching Telegram's pattern: [image: /path] or [file: /path]
+ if media_paths:
+ for p in media_paths:
+ mime, _ = mimetypes.guess_type(p)
+ media_type = "image" if mime and mime.startswith("image/") else "file"
+ media_tag = f"[{media_type}: {p}]"
+ content = f"{content}\n{media_tag}" if content else media_tag
+
+ await self._handle_message(
+ sender_id=sender_id,
+ chat_id=sender, # Use full LID for replies
+ content=content,
+ media=media_paths,
+ metadata={
+ "message_id": message_id,
+ "timestamp": data.get("timestamp"),
+ "is_group": data.get("isGroup", False)
+ }
+ )
+
+ elif msg_type == "status":
+ # Connection status update
+ status = data.get("status")
+ logger.info("WhatsApp status: {}", status)
+
+ if status == "connected":
+ self._connected = True
+ elif status == "disconnected":
+ self._connected = False
+
+ elif msg_type == "qr":
+ # QR code for authentication
+ logger.info("Scan QR code in the bridge terminal to connect WhatsApp")
+
+ elif msg_type == "error":
+ logger.error("WhatsApp bridge error: {}", data.get('error'))
diff --git a/nanobot/nanobot/cli/__init__.py b/nanobot/nanobot/cli/__init__.py
new file mode 100644
index 0000000..b023cad
--- /dev/null
+++ b/nanobot/nanobot/cli/__init__.py
@@ -0,0 +1 @@
+"""CLI module for nanobot."""
diff --git a/nanobot/nanobot/cli/commands.py b/nanobot/nanobot/cli/commands.py
new file mode 100644
index 0000000..2c8d6d3
--- /dev/null
+++ b/nanobot/nanobot/cli/commands.py
@@ -0,0 +1,975 @@
+"""CLI commands for nanobot."""
+
+import asyncio
+import os
+import select
+import signal
+import sys
+from pathlib import Path
+
+# Force UTF-8 encoding for Windows console
+if sys.platform == "win32":
+ if sys.stdout.encoding != "utf-8":
+ os.environ["PYTHONIOENCODING"] = "utf-8"
+ # Re-open stdout/stderr with UTF-8 encoding
+ try:
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+ sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+ except Exception:
+ pass
+
+import typer
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.patch_stdout import patch_stdout
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+from rich.text import Text
+
+from nanobot import __logo__, __version__
+from nanobot.config.paths import get_workspace_path
+from nanobot.config.schema import Config
+from nanobot.utils.helpers import sync_workspace_templates
+
+app = typer.Typer(
+ name="nanobot",
+ help=f"{__logo__} nanobot - Personal AI Assistant",
+ no_args_is_help=True,
+)
+
+console = Console()
+EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q"}
+
+# ---------------------------------------------------------------------------
+# CLI input: prompt_toolkit for editing, paste, history, and display
+# ---------------------------------------------------------------------------
+
+_PROMPT_SESSION: PromptSession | None = None
+_SAVED_TERM_ATTRS = None # original termios settings, restored on exit
+
+
+def _flush_pending_tty_input() -> None:
+ """Drop unread keypresses typed while the model was generating output."""
+ try:
+ fd = sys.stdin.fileno()
+ if not os.isatty(fd):
+ return
+ except Exception:
+ return
+
+ try:
+ import termios
+ termios.tcflush(fd, termios.TCIFLUSH)
+ return
+ except Exception:
+ pass
+
+ try:
+ while True:
+ ready, _, _ = select.select([fd], [], [], 0)
+ if not ready:
+ break
+ if not os.read(fd, 4096):
+ break
+ except Exception:
+ return
+
+
+def _restore_terminal() -> None:
+ """Restore terminal to its original state (echo, line buffering, etc.)."""
+ if _SAVED_TERM_ATTRS is None:
+ return
+ try:
+ import termios
+ termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, _SAVED_TERM_ATTRS)
+ except Exception:
+ pass
+
+
+def _init_prompt_session() -> None:
+ """Create the prompt_toolkit session with persistent file history."""
+ global _PROMPT_SESSION, _SAVED_TERM_ATTRS
+
+ # Save terminal state so we can restore it on exit
+ try:
+ import termios
+ _SAVED_TERM_ATTRS = termios.tcgetattr(sys.stdin.fileno())
+ except Exception:
+ pass
+
+ from nanobot.config.paths import get_cli_history_path
+
+ history_file = get_cli_history_path()
+ history_file.parent.mkdir(parents=True, exist_ok=True)
+
+ _PROMPT_SESSION = PromptSession(
+ history=FileHistory(str(history_file)),
+ enable_open_in_editor=False,
+ multiline=False, # Enter submits (single line mode)
+ )
+
+
+def _print_agent_response(response: str, render_markdown: bool) -> None:
+ """Render assistant response with consistent terminal styling."""
+ content = response or ""
+ body = Markdown(content) if render_markdown else Text(content)
+ console.print()
+ console.print(f"[cyan]{__logo__} nanobot[/cyan]")
+ console.print(body)
+ console.print()
+
+
+def _is_exit_command(command: str) -> bool:
+ """Return True when input should end interactive chat."""
+ return command.lower() in EXIT_COMMANDS
+
+
+async def _read_interactive_input_async() -> str:
+ """Read user input using prompt_toolkit (handles paste, history, display).
+
+ prompt_toolkit natively handles:
+ - Multiline paste (bracketed paste mode)
+ - History navigation (up/down arrows)
+ - Clean display (no ghost characters or artifacts)
+ """
+ if _PROMPT_SESSION is None:
+ raise RuntimeError("Call _init_prompt_session() first")
+ try:
+ with patch_stdout():
+ return await _PROMPT_SESSION.prompt_async(
+ HTML("You: "),
+ )
+ except EOFError as exc:
+ raise KeyboardInterrupt from exc
+
+
+
+def version_callback(value: bool):
+ if value:
+ console.print(f"{__logo__} nanobot v{__version__}")
+ raise typer.Exit()
+
+
+@app.callback()
+def main(
+ version: bool = typer.Option(
+ None, "--version", "-v", callback=version_callback, is_eager=True
+ ),
+):
+ """nanobot - Personal AI Assistant."""
+ pass
+
+
+# ============================================================================
+# Onboard / Setup
+# ============================================================================
+
+
+@app.command()
+def onboard():
+ """Initialize nanobot configuration and workspace."""
+ from nanobot.config.loader import get_config_path, load_config, save_config
+ from nanobot.config.schema import Config
+
+ config_path = get_config_path()
+
+ if config_path.exists():
+ console.print(f"[yellow]Config already exists at {config_path}[/yellow]")
+ console.print(" [bold]y[/bold] = overwrite with defaults (existing values will be lost)")
+ console.print(" [bold]N[/bold] = refresh config, keeping existing values and adding new fields")
+ if typer.confirm("Overwrite?"):
+ config = Config()
+ save_config(config)
+ console.print(f"[green]✓[/green] Config reset to defaults at {config_path}")
+ else:
+ config = load_config()
+ save_config(config)
+ console.print(f"[green]✓[/green] Config refreshed at {config_path} (existing values preserved)")
+ else:
+ save_config(Config())
+ console.print(f"[green]✓[/green] Created config at {config_path}")
+
+ # Create workspace
+ workspace = get_workspace_path()
+
+ if not workspace.exists():
+ workspace.mkdir(parents=True, exist_ok=True)
+ console.print(f"[green]✓[/green] Created workspace at {workspace}")
+
+ sync_workspace_templates(workspace)
+
+ console.print(f"\n{__logo__} nanobot is ready!")
+ console.print("\nNext steps:")
+ console.print(" 1. Add your API key to [cyan]~/.nanobot/config.json[/cyan]")
+ console.print(" Get one at: https://openrouter.ai/keys")
+ console.print(" 2. Chat: [cyan]nanobot agent -m \"Hello!\"[/cyan]")
+ console.print("\n[dim]Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps[/dim]")
+
+
+
+
+
+def _make_provider(config: Config):
+ """Create the appropriate LLM provider from config."""
+ from nanobot.providers.openai_codex_provider import OpenAICodexProvider
+ from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+
+ model = config.agents.defaults.model
+ provider_name = config.get_provider_name(model)
+ p = config.get_provider(model)
+
+ # OpenAI Codex (OAuth)
+ if provider_name == "openai_codex" or model.startswith("openai-codex/"):
+ return OpenAICodexProvider(default_model=model)
+
+ # Custom: direct OpenAI-compatible endpoint, bypasses LiteLLM
+ from nanobot.providers.custom_provider import CustomProvider
+ if provider_name == "custom":
+ return CustomProvider(
+ api_key=p.api_key if p else "no-key",
+ api_base=config.get_api_base(model) or "http://localhost:8000/v1",
+ default_model=model,
+ )
+
+ # Azure OpenAI: direct Azure OpenAI endpoint with deployment name
+ if provider_name == "azure_openai":
+ if not p or not p.api_key or not p.api_base:
+ console.print("[red]Error: Azure OpenAI requires api_key and api_base.[/red]")
+ console.print("Set them in ~/.nanobot/config.json under providers.azure_openai section")
+ console.print("Use the model field to specify the deployment name.")
+ raise typer.Exit(1)
+
+ return AzureOpenAIProvider(
+ api_key=p.api_key,
+ api_base=p.api_base,
+ default_model=model,
+ )
+
+ from nanobot.providers.litellm_provider import LiteLLMProvider
+ from nanobot.providers.registry import find_by_name
+ spec = find_by_name(provider_name)
+ if not model.startswith("bedrock/") and not (p and p.api_key) and not (spec and spec.is_oauth):
+ console.print("[red]Error: No API key configured.[/red]")
+ console.print("Set one in ~/.nanobot/config.json under providers section")
+ raise typer.Exit(1)
+
+ return LiteLLMProvider(
+ api_key=p.api_key if p else None,
+ api_base=config.get_api_base(model),
+ default_model=model,
+ extra_headers=p.extra_headers if p else None,
+ provider_name=provider_name,
+ )
+
+
+def _load_runtime_config(config: str | None = None, workspace: str | None = None) -> Config:
+ """Load config and optionally override the active workspace."""
+ from nanobot.config.loader import load_config, set_config_path
+
+ config_path = None
+ if config:
+ config_path = Path(config).expanduser().resolve()
+ if not config_path.exists():
+ console.print(f"[red]Error: Config file not found: {config_path}[/red]")
+ raise typer.Exit(1)
+ set_config_path(config_path)
+ console.print(f"[dim]Using config: {config_path}[/dim]")
+
+ loaded = load_config(config_path)
+ if workspace:
+ loaded.agents.defaults.workspace = workspace
+ return loaded
+
+
+# ============================================================================
+# Gateway / Server
+# ============================================================================
+
+
+@app.command()
+def gateway(
+ port: int = typer.Option(18790, "--port", "-p", help="Gateway port"),
+ workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+ config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+):
+ """Start the nanobot gateway."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.queue import MessageBus
+ from nanobot.channels.manager import ChannelManager
+ from nanobot.config.paths import get_cron_dir
+ from nanobot.cron.service import CronService
+ from nanobot.cron.types import CronJob
+ from nanobot.heartbeat.service import HeartbeatService
+ from nanobot.session.manager import SessionManager
+
+ if verbose:
+ import logging
+ logging.basicConfig(level=logging.DEBUG)
+
+ config = _load_runtime_config(config, workspace)
+
+ console.print(f"{__logo__} Starting nanobot gateway on port {port}...")
+ sync_workspace_templates(config.workspace_path)
+ bus = MessageBus()
+ provider = _make_provider(config)
+ session_manager = SessionManager(config.workspace_path)
+
+ # Create cron service first (callback set after agent creation)
+ cron_store_path = get_cron_dir() / "jobs.json"
+ cron = CronService(cron_store_path)
+
+ # Create agent with cron service
+ agent = AgentLoop(
+ bus=bus,
+ provider=provider,
+ workspace=config.workspace_path,
+ model=config.agents.defaults.model,
+ temperature=config.agents.defaults.temperature,
+ max_tokens=config.agents.defaults.max_tokens,
+ max_iterations=config.agents.defaults.max_tool_iterations,
+ memory_window=config.agents.defaults.memory_window,
+ reasoning_effort=config.agents.defaults.reasoning_effort,
+ brave_api_key=config.tools.web.search.api_key or None,
+ web_proxy=config.tools.web.proxy or None,
+ exec_config=config.tools.exec,
+ cron_service=cron,
+ restrict_to_workspace=config.tools.restrict_to_workspace,
+ session_manager=session_manager,
+ mcp_servers=config.tools.mcp_servers,
+ channels_config=config.channels,
+ )
+
+ # Set cron callback (needs agent)
+ async def on_cron_job(job: CronJob) -> str | None:
+ """Execute a cron job through the agent."""
+ from nanobot.agent.tools.cron import CronTool
+ from nanobot.agent.tools.message import MessageTool
+ reminder_note = (
+ "[Scheduled Task] Timer finished.\n\n"
+ f"Task '{job.name}' has been triggered.\n"
+ f"Scheduled instruction: {job.payload.message}"
+ )
+
+ # Prevent the agent from scheduling new cron jobs during execution
+ cron_tool = agent.tools.get("cron")
+ cron_token = None
+ if isinstance(cron_tool, CronTool):
+ cron_token = cron_tool.set_cron_context(True)
+ try:
+ response = await agent.process_direct(
+ reminder_note,
+ session_key=f"cron:{job.id}",
+ channel=job.payload.channel or "cli",
+ chat_id=job.payload.to or "direct",
+ )
+ finally:
+ if isinstance(cron_tool, CronTool) and cron_token is not None:
+ cron_tool.reset_cron_context(cron_token)
+
+ message_tool = agent.tools.get("message")
+ if isinstance(message_tool, MessageTool) and message_tool._sent_in_turn:
+ return response
+
+ if job.payload.deliver and job.payload.to and response:
+ from nanobot.bus.events import OutboundMessage
+ await bus.publish_outbound(OutboundMessage(
+ channel=job.payload.channel or "cli",
+ chat_id=job.payload.to,
+ content=response
+ ))
+ return response
+ cron.on_job = on_cron_job
+
+ # Create channel manager
+ channels = ChannelManager(config, bus)
+
+ def _pick_heartbeat_target() -> tuple[str, str]:
+ """Pick a routable channel/chat target for heartbeat-triggered messages."""
+ enabled = set(channels.enabled_channels)
+ # Prefer the most recently updated non-internal session on an enabled channel.
+ for item in session_manager.list_sessions():
+ key = item.get("key") or ""
+ if ":" not in key:
+ continue
+ channel, chat_id = key.split(":", 1)
+ if channel in {"cli", "system"}:
+ continue
+ if channel in enabled and chat_id:
+ return channel, chat_id
+ # Fallback keeps prior behavior but remains explicit.
+ return "cli", "direct"
+
+ # Create heartbeat service
+ async def on_heartbeat_execute(tasks: str) -> str:
+ """Phase 2: execute heartbeat tasks through the full agent loop."""
+ channel, chat_id = _pick_heartbeat_target()
+
+ async def _silent(*_args, **_kwargs):
+ pass
+
+ return await agent.process_direct(
+ tasks,
+ session_key="heartbeat",
+ channel=channel,
+ chat_id=chat_id,
+ on_progress=_silent,
+ )
+
+ async def on_heartbeat_notify(response: str) -> None:
+ """Deliver a heartbeat response to the user's channel."""
+ from nanobot.bus.events import OutboundMessage
+ channel, chat_id = _pick_heartbeat_target()
+ if channel == "cli":
+ return # No external channel available to deliver to
+ await bus.publish_outbound(OutboundMessage(channel=channel, chat_id=chat_id, content=response))
+
+ hb_cfg = config.gateway.heartbeat
+ heartbeat = HeartbeatService(
+ workspace=config.workspace_path,
+ provider=provider,
+ model=agent.model,
+ on_execute=on_heartbeat_execute,
+ on_notify=on_heartbeat_notify,
+ interval_s=hb_cfg.interval_s,
+ enabled=hb_cfg.enabled,
+ )
+
+ if channels.enabled_channels:
+ console.print(f"[green]✓[/green] Channels enabled: {', '.join(channels.enabled_channels)}")
+ else:
+ console.print("[yellow]Warning: No channels enabled[/yellow]")
+
+ cron_status = cron.status()
+ if cron_status["jobs"] > 0:
+ console.print(f"[green]✓[/green] Cron: {cron_status['jobs']} scheduled jobs")
+
+ console.print(f"[green]✓[/green] Heartbeat: every {hb_cfg.interval_s}s")
+
+ async def run():
+ try:
+ await cron.start()
+ await heartbeat.start()
+ await asyncio.gather(
+ agent.run(),
+ channels.start_all(),
+ )
+ except KeyboardInterrupt:
+ console.print("\nShutting down...")
+ finally:
+ await agent.close_mcp()
+ heartbeat.stop()
+ cron.stop()
+ agent.stop()
+ await channels.stop_all()
+
+ asyncio.run(run())
+
+
+
+
+# ============================================================================
+# Agent Commands
+# ============================================================================
+
+
+@app.command()
+def agent(
+ message: str = typer.Option(None, "--message", "-m", help="Message to send to the agent"),
+ session_id: str = typer.Option("cli:direct", "--session", "-s", help="Session ID"),
+ workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+ config: str | None = typer.Option(None, "--config", "-c", help="Config file path"),
+ markdown: bool = typer.Option(True, "--markdown/--no-markdown", help="Render assistant output as Markdown"),
+ logs: bool = typer.Option(False, "--logs/--no-logs", help="Show nanobot runtime logs during chat"),
+):
+ """Interact with the agent directly."""
+ from loguru import logger
+
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.queue import MessageBus
+ from nanobot.config.paths import get_cron_dir
+ from nanobot.cron.service import CronService
+
+ config = _load_runtime_config(config, workspace)
+ sync_workspace_templates(config.workspace_path)
+
+ bus = MessageBus()
+ provider = _make_provider(config)
+
+ # Create cron service for tool usage (no callback needed for CLI unless running)
+ cron_store_path = get_cron_dir() / "jobs.json"
+ cron = CronService(cron_store_path)
+
+ if logs:
+ logger.enable("nanobot")
+ else:
+ logger.disable("nanobot")
+
+ agent_loop = AgentLoop(
+ bus=bus,
+ provider=provider,
+ workspace=config.workspace_path,
+ model=config.agents.defaults.model,
+ temperature=config.agents.defaults.temperature,
+ max_tokens=config.agents.defaults.max_tokens,
+ max_iterations=config.agents.defaults.max_tool_iterations,
+ memory_window=config.agents.defaults.memory_window,
+ reasoning_effort=config.agents.defaults.reasoning_effort,
+ brave_api_key=config.tools.web.search.api_key or None,
+ web_proxy=config.tools.web.proxy or None,
+ exec_config=config.tools.exec,
+ cron_service=cron,
+ restrict_to_workspace=config.tools.restrict_to_workspace,
+ mcp_servers=config.tools.mcp_servers,
+ channels_config=config.channels,
+ )
+
+ # Show spinner when logs are off (no output to miss); skip when logs are on
+ def _thinking_ctx():
+ if logs:
+ from contextlib import nullcontext
+ return nullcontext()
+ # Animated spinner is safe to use with prompt_toolkit input handling
+ return console.status("[dim]nanobot is thinking...[/dim]", spinner="dots")
+
+ async def _cli_progress(content: str, *, tool_hint: bool = False) -> None:
+ ch = agent_loop.channels_config
+ if ch and tool_hint and not ch.send_tool_hints:
+ return
+ if ch and not tool_hint and not ch.send_progress:
+ return
+ console.print(f" [dim]↳ {content}[/dim]")
+
+ if message:
+ # Single message mode — direct call, no bus needed
+ async def run_once():
+ with _thinking_ctx():
+ response = await agent_loop.process_direct(message, session_id, on_progress=_cli_progress)
+ _print_agent_response(response, render_markdown=markdown)
+ await agent_loop.close_mcp()
+
+ asyncio.run(run_once())
+ else:
+ # Interactive mode — route through bus like other channels
+ from nanobot.bus.events import InboundMessage
+ _init_prompt_session()
+ console.print(f"{__logo__} Interactive mode (type [bold]exit[/bold] or [bold]Ctrl+C[/bold] to quit)\n")
+
+ if ":" in session_id:
+ cli_channel, cli_chat_id = session_id.split(":", 1)
+ else:
+ cli_channel, cli_chat_id = "cli", session_id
+
+ def _handle_signal(signum, frame):
+ sig_name = signal.Signals(signum).name
+ _restore_terminal()
+ console.print(f"\nReceived {sig_name}, goodbye!")
+ sys.exit(0)
+
+ signal.signal(signal.SIGINT, _handle_signal)
+ signal.signal(signal.SIGTERM, _handle_signal)
+ # SIGHUP is not available on Windows
+ if hasattr(signal, 'SIGHUP'):
+ signal.signal(signal.SIGHUP, _handle_signal)
+ # Ignore SIGPIPE to prevent silent process termination when writing to closed pipes
+ # SIGPIPE is not available on Windows
+ if hasattr(signal, 'SIGPIPE'):
+ signal.signal(signal.SIGPIPE, signal.SIG_IGN)
+
+ async def run_interactive():
+ bus_task = asyncio.create_task(agent_loop.run())
+ turn_done = asyncio.Event()
+ turn_done.set()
+ turn_response: list[str] = []
+
+ async def _consume_outbound():
+ while True:
+ try:
+ msg = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+ if msg.metadata.get("_progress"):
+ is_tool_hint = msg.metadata.get("_tool_hint", False)
+ ch = agent_loop.channels_config
+ if ch and is_tool_hint and not ch.send_tool_hints:
+ pass
+ elif ch and not is_tool_hint and not ch.send_progress:
+ pass
+ else:
+ console.print(f" [dim]↳ {msg.content}[/dim]")
+ elif not turn_done.is_set():
+ if msg.content:
+ turn_response.append(msg.content)
+ turn_done.set()
+ elif msg.content:
+ console.print()
+ _print_agent_response(msg.content, render_markdown=markdown)
+ except asyncio.TimeoutError:
+ continue
+ except asyncio.CancelledError:
+ break
+
+ outbound_task = asyncio.create_task(_consume_outbound())
+
+ try:
+ while True:
+ try:
+ _flush_pending_tty_input()
+ user_input = await _read_interactive_input_async()
+ command = user_input.strip()
+ if not command:
+ continue
+
+ if _is_exit_command(command):
+ _restore_terminal()
+ console.print("\nGoodbye!")
+ break
+
+ turn_done.clear()
+ turn_response.clear()
+
+ await bus.publish_inbound(InboundMessage(
+ channel=cli_channel,
+ sender_id="user",
+ chat_id=cli_chat_id,
+ content=user_input,
+ ))
+
+ with _thinking_ctx():
+ await turn_done.wait()
+
+ if turn_response:
+ _print_agent_response(turn_response[0], render_markdown=markdown)
+ except KeyboardInterrupt:
+ _restore_terminal()
+ console.print("\nGoodbye!")
+ break
+ except EOFError:
+ _restore_terminal()
+ console.print("\nGoodbye!")
+ break
+ finally:
+ agent_loop.stop()
+ outbound_task.cancel()
+ await asyncio.gather(bus_task, outbound_task, return_exceptions=True)
+ await agent_loop.close_mcp()
+
+ asyncio.run(run_interactive())
+
+
+# ============================================================================
+# Channel Commands
+# ============================================================================
+
+
+channels_app = typer.Typer(help="Manage channels")
+app.add_typer(channels_app, name="channels")
+
+
+@channels_app.command("status")
+def channels_status():
+ """Show channel status."""
+ from nanobot.config.loader import load_config
+
+ config = load_config()
+
+ table = Table(title="Channel Status")
+ table.add_column("Channel", style="cyan")
+ table.add_column("Enabled", style="green")
+ table.add_column("Configuration", style="yellow")
+
+ # WhatsApp
+ wa = config.channels.whatsapp
+ table.add_row(
+ "WhatsApp",
+ "✓" if wa.enabled else "✗",
+ wa.bridge_url
+ )
+
+ dc = config.channels.discord
+ table.add_row(
+ "Discord",
+ "✓" if dc.enabled else "✗",
+ dc.gateway_url
+ )
+
+ # Feishu
+ fs = config.channels.feishu
+ fs_config = f"app_id: {fs.app_id[:10]}..." if fs.app_id else "[dim]not configured[/dim]"
+ table.add_row(
+ "Feishu",
+ "✓" if fs.enabled else "✗",
+ fs_config
+ )
+
+ # Mochat
+ mc = config.channels.mochat
+ mc_base = mc.base_url or "[dim]not configured[/dim]"
+ table.add_row(
+ "Mochat",
+ "✓" if mc.enabled else "✗",
+ mc_base
+ )
+
+ # Telegram
+ tg = config.channels.telegram
+ tg_config = f"token: {tg.token[:10]}..." if tg.token else "[dim]not configured[/dim]"
+ table.add_row(
+ "Telegram",
+ "✓" if tg.enabled else "✗",
+ tg_config
+ )
+
+ # Slack
+ slack = config.channels.slack
+ slack_config = "socket" if slack.app_token and slack.bot_token else "[dim]not configured[/dim]"
+ table.add_row(
+ "Slack",
+ "✓" if slack.enabled else "✗",
+ slack_config
+ )
+
+ # DingTalk
+ dt = config.channels.dingtalk
+ dt_config = f"client_id: {dt.client_id[:10]}..." if dt.client_id else "[dim]not configured[/dim]"
+ table.add_row(
+ "DingTalk",
+ "✓" if dt.enabled else "✗",
+ dt_config
+ )
+
+ # QQ
+ qq = config.channels.qq
+ qq_config = f"app_id: {qq.app_id[:10]}..." if qq.app_id else "[dim]not configured[/dim]"
+ table.add_row(
+ "QQ",
+ "✓" if qq.enabled else "✗",
+ qq_config
+ )
+
+ # Email
+ em = config.channels.email
+ em_config = em.imap_host if em.imap_host else "[dim]not configured[/dim]"
+ table.add_row(
+ "Email",
+ "✓" if em.enabled else "✗",
+ em_config
+ )
+
+ console.print(table)
+
+
+def _get_bridge_dir() -> Path:
+ """Get the bridge directory, setting it up if needed."""
+ import shutil
+ import subprocess
+
+ # User's bridge location
+ from nanobot.config.paths import get_bridge_install_dir
+
+ user_bridge = get_bridge_install_dir()
+
+ # Check if already built
+ if (user_bridge / "dist" / "index.js").exists():
+ return user_bridge
+
+ # Check for npm
+ if not shutil.which("npm"):
+ console.print("[red]npm not found. Please install Node.js >= 18.[/red]")
+ raise typer.Exit(1)
+
+ # Find source bridge: first check package data, then source dir
+ pkg_bridge = Path(__file__).parent.parent / "bridge" # nanobot/bridge (installed)
+ src_bridge = Path(__file__).parent.parent.parent / "bridge" # repo root/bridge (dev)
+
+ source = None
+ if (pkg_bridge / "package.json").exists():
+ source = pkg_bridge
+ elif (src_bridge / "package.json").exists():
+ source = src_bridge
+
+ if not source:
+ console.print("[red]Bridge source not found.[/red]")
+ console.print("Try reinstalling: pip install --force-reinstall nanobot")
+ raise typer.Exit(1)
+
+ console.print(f"{__logo__} Setting up bridge...")
+
+ # Copy to user directory
+ user_bridge.parent.mkdir(parents=True, exist_ok=True)
+ if user_bridge.exists():
+ shutil.rmtree(user_bridge)
+ shutil.copytree(source, user_bridge, ignore=shutil.ignore_patterns("node_modules", "dist"))
+
+ # Install and build
+ try:
+ console.print(" Installing dependencies...")
+ subprocess.run(["npm", "install"], cwd=user_bridge, check=True, capture_output=True)
+
+ console.print(" Building...")
+ subprocess.run(["npm", "run", "build"], cwd=user_bridge, check=True, capture_output=True)
+
+ console.print("[green]✓[/green] Bridge ready\n")
+ except subprocess.CalledProcessError as e:
+ console.print(f"[red]Build failed: {e}[/red]")
+ if e.stderr:
+ console.print(f"[dim]{e.stderr.decode()[:500]}[/dim]")
+ raise typer.Exit(1)
+
+ return user_bridge
+
+
+@channels_app.command("login")
+def channels_login():
+ """Link device via QR code."""
+ import subprocess
+
+ from nanobot.config.loader import load_config
+ from nanobot.config.paths import get_runtime_subdir
+
+ config = load_config()
+ bridge_dir = _get_bridge_dir()
+
+ console.print(f"{__logo__} Starting bridge...")
+ console.print("Scan the QR code to connect.\n")
+
+ env = {**os.environ}
+ if config.channels.whatsapp.bridge_token:
+ env["BRIDGE_TOKEN"] = config.channels.whatsapp.bridge_token
+ env["AUTH_DIR"] = str(get_runtime_subdir("whatsapp-auth"))
+
+ try:
+ subprocess.run(["npm", "start"], cwd=bridge_dir, check=True, env=env)
+ except subprocess.CalledProcessError as e:
+ console.print(f"[red]Bridge failed: {e}[/red]")
+ except FileNotFoundError:
+ console.print("[red]npm not found. Please install Node.js.[/red]")
+
+
+# ============================================================================
+# Status Commands
+# ============================================================================
+
+
+@app.command()
+def status():
+ """Show nanobot status."""
+ from nanobot.config.loader import get_config_path, load_config
+
+ config_path = get_config_path()
+ config = load_config()
+ workspace = config.workspace_path
+
+ console.print(f"{__logo__} nanobot Status\n")
+
+ console.print(f"Config: {config_path} {'[green]✓[/green]' if config_path.exists() else '[red]✗[/red]'}")
+ console.print(f"Workspace: {workspace} {'[green]✓[/green]' if workspace.exists() else '[red]✗[/red]'}")
+
+ if config_path.exists():
+ from nanobot.providers.registry import PROVIDERS
+
+ console.print(f"Model: {config.agents.defaults.model}")
+
+ # Check API keys from registry
+ for spec in PROVIDERS:
+ p = getattr(config.providers, spec.name, None)
+ if p is None:
+ continue
+ if spec.is_oauth:
+ console.print(f"{spec.label}: [green]✓ (OAuth)[/green]")
+ elif spec.is_local:
+ # Local deployments show api_base instead of api_key
+ if p.api_base:
+ console.print(f"{spec.label}: [green]✓ {p.api_base}[/green]")
+ else:
+ console.print(f"{spec.label}: [dim]not set[/dim]")
+ else:
+ has_key = bool(p.api_key)
+ console.print(f"{spec.label}: {'[green]✓[/green]' if has_key else '[dim]not set[/dim]'}")
+
+
+# ============================================================================
+# OAuth Login
+# ============================================================================
+
+provider_app = typer.Typer(help="Manage providers")
+app.add_typer(provider_app, name="provider")
+
+
+_LOGIN_HANDLERS: dict[str, callable] = {}
+
+
+def _register_login(name: str):
+ def decorator(fn):
+ _LOGIN_HANDLERS[name] = fn
+ return fn
+ return decorator
+
+
+@provider_app.command("login")
+def provider_login(
+ provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot')"),
+):
+ """Authenticate with an OAuth provider."""
+ from nanobot.providers.registry import PROVIDERS
+
+ key = provider.replace("-", "_")
+ spec = next((s for s in PROVIDERS if s.name == key and s.is_oauth), None)
+ if not spec:
+ names = ", ".join(s.name.replace("_", "-") for s in PROVIDERS if s.is_oauth)
+ console.print(f"[red]Unknown OAuth provider: {provider}[/red] Supported: {names}")
+ raise typer.Exit(1)
+
+ handler = _LOGIN_HANDLERS.get(spec.name)
+ if not handler:
+ console.print(f"[red]Login not implemented for {spec.label}[/red]")
+ raise typer.Exit(1)
+
+ console.print(f"{__logo__} OAuth Login - {spec.label}\n")
+ handler()
+
+
+@_register_login("openai_codex")
+def _login_openai_codex() -> None:
+ try:
+ from oauth_cli_kit import get_token, login_oauth_interactive
+ token = None
+ try:
+ token = get_token()
+ except Exception:
+ pass
+ if not (token and token.access):
+ console.print("[cyan]Starting interactive OAuth login...[/cyan]\n")
+ token = login_oauth_interactive(
+ print_fn=lambda s: console.print(s),
+ prompt_fn=lambda s: typer.prompt(s),
+ )
+ if not (token and token.access):
+ console.print("[red]✗ Authentication failed[/red]")
+ raise typer.Exit(1)
+ console.print(f"[green]✓ Authenticated with OpenAI Codex[/green] [dim]{token.account_id}[/dim]")
+ except ImportError:
+ console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")
+ raise typer.Exit(1)
+
+
+@_register_login("github_copilot")
+def _login_github_copilot() -> None:
+ import asyncio
+
+ console.print("[cyan]Starting GitHub Copilot device flow...[/cyan]\n")
+
+ async def _trigger():
+ from litellm import acompletion
+ await acompletion(model="github_copilot/gpt-4o", messages=[{"role": "user", "content": "hi"}], max_tokens=1)
+
+ try:
+ asyncio.run(_trigger())
+ console.print("[green]✓ Authenticated with GitHub Copilot[/green]")
+ except Exception as e:
+ console.print(f"[red]Authentication error: {e}[/red]")
+ raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+ app()
diff --git a/nanobot/nanobot/config/__init__.py b/nanobot/nanobot/config/__init__.py
new file mode 100644
index 0000000..e2c24f8
--- /dev/null
+++ b/nanobot/nanobot/config/__init__.py
@@ -0,0 +1,30 @@
+"""Configuration module for nanobot."""
+
+from nanobot.config.loader import get_config_path, load_config
+from nanobot.config.paths import (
+ get_bridge_install_dir,
+ get_cli_history_path,
+ get_cron_dir,
+ get_data_dir,
+ get_legacy_sessions_dir,
+ get_logs_dir,
+ get_media_dir,
+ get_runtime_subdir,
+ get_workspace_path,
+)
+from nanobot.config.schema import Config
+
+__all__ = [
+ "Config",
+ "load_config",
+ "get_config_path",
+ "get_data_dir",
+ "get_runtime_subdir",
+ "get_media_dir",
+ "get_cron_dir",
+ "get_logs_dir",
+ "get_workspace_path",
+ "get_cli_history_path",
+ "get_bridge_install_dir",
+ "get_legacy_sessions_dir",
+]
diff --git a/nanobot/nanobot/config/loader.py b/nanobot/nanobot/config/loader.py
new file mode 100644
index 0000000..7d309e5
--- /dev/null
+++ b/nanobot/nanobot/config/loader.py
@@ -0,0 +1,75 @@
+"""Configuration loading utilities."""
+
+import json
+from pathlib import Path
+
+from nanobot.config.schema import Config
+
+
+# Global variable to store current config path (for multi-instance support)
+_current_config_path: Path | None = None
+
+
+def set_config_path(path: Path) -> None:
+ """Set the current config path (used to derive data directory)."""
+ global _current_config_path
+ _current_config_path = path
+
+
+def get_config_path() -> Path:
+ """Get the configuration file path."""
+ if _current_config_path:
+ return _current_config_path
+ return Path.home() / ".nanobot" / "config.json"
+
+
+def load_config(config_path: Path | None = None) -> Config:
+ """
+ Load configuration from file or create default.
+
+ Args:
+ config_path: Optional path to config file. Uses default if not provided.
+
+ Returns:
+ Loaded configuration object.
+ """
+ path = config_path or get_config_path()
+
+ if path.exists():
+ try:
+ with open(path, encoding="utf-8") as f:
+ data = json.load(f)
+ data = _migrate_config(data)
+ return Config.model_validate(data)
+ except (json.JSONDecodeError, ValueError) as e:
+ print(f"Warning: Failed to load config from {path}: {e}")
+ print("Using default configuration.")
+
+ return Config()
+
+
+def save_config(config: Config, config_path: Path | None = None) -> None:
+ """
+ Save configuration to file.
+
+ Args:
+ config: Configuration to save.
+ config_path: Optional path to save to. Uses default if not provided.
+ """
+ path = config_path or get_config_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+
+ data = config.model_dump(by_alias=True)
+
+ with open(path, "w", encoding="utf-8") as f:
+ json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+def _migrate_config(data: dict) -> dict:
+ """Migrate old config formats to current."""
+ # Move tools.exec.restrictToWorkspace → tools.restrictToWorkspace
+ tools = data.get("tools", {})
+ exec_cfg = tools.get("exec", {})
+ if "restrictToWorkspace" in exec_cfg and "restrictToWorkspace" not in tools:
+ tools["restrictToWorkspace"] = exec_cfg.pop("restrictToWorkspace")
+ return data
diff --git a/nanobot/nanobot/config/paths.py b/nanobot/nanobot/config/paths.py
new file mode 100644
index 0000000..f4dfbd9
--- /dev/null
+++ b/nanobot/nanobot/config/paths.py
@@ -0,0 +1,55 @@
+"""Runtime path helpers derived from the active config context."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from nanobot.config.loader import get_config_path
+from nanobot.utils.helpers import ensure_dir
+
+
+def get_data_dir() -> Path:
+ """Return the instance-level runtime data directory."""
+ return ensure_dir(get_config_path().parent)
+
+
+def get_runtime_subdir(name: str) -> Path:
+ """Return a named runtime subdirectory under the instance data dir."""
+ return ensure_dir(get_data_dir() / name)
+
+
+def get_media_dir(channel: str | None = None) -> Path:
+ """Return the media directory, optionally namespaced per channel."""
+ base = get_runtime_subdir("media")
+ return ensure_dir(base / channel) if channel else base
+
+
+def get_cron_dir() -> Path:
+ """Return the cron storage directory."""
+ return get_runtime_subdir("cron")
+
+
+def get_logs_dir() -> Path:
+ """Return the logs directory."""
+ return get_runtime_subdir("logs")
+
+
+def get_workspace_path(workspace: str | None = None) -> Path:
+ """Resolve and ensure the agent workspace path."""
+ path = Path(workspace).expanduser() if workspace else Path.home() / ".nanobot" / "workspace"
+ return ensure_dir(path)
+
+
+def get_cli_history_path() -> Path:
+ """Return the shared CLI history file path."""
+ return Path.home() / ".nanobot" / "history" / "cli_history"
+
+
+def get_bridge_install_dir() -> Path:
+ """Return the shared WhatsApp bridge installation directory."""
+ return Path.home() / ".nanobot" / "bridge"
+
+
+def get_legacy_sessions_dir() -> Path:
+ """Return the legacy global session directory used for migration fallback."""
+ return Path.home() / ".nanobot" / "sessions"
diff --git a/nanobot/nanobot/config/schema.py b/nanobot/nanobot/config/schema.py
new file mode 100644
index 0000000..803cb61
--- /dev/null
+++ b/nanobot/nanobot/config/schema.py
@@ -0,0 +1,421 @@
+"""Configuration schema using Pydantic."""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+from pydantic_settings import BaseSettings
+
+
+class Base(BaseModel):
+ """Base model that accepts both camelCase and snake_case keys."""
+
+ model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class WhatsAppConfig(Base):
+ """WhatsApp channel configuration."""
+
+ enabled: bool = False
+ bridge_url: str = "ws://localhost:3001"
+ bridge_token: str = "" # Shared token for bridge auth (optional, recommended)
+ allow_from: list[str] = Field(default_factory=list) # Allowed phone numbers
+
+
+class TelegramConfig(Base):
+ """Telegram channel configuration."""
+
+ enabled: bool = False
+ token: str = "" # Bot token from @BotFather
+ allow_from: list[str] = Field(default_factory=list) # Allowed user IDs or usernames
+ proxy: str | None = (
+ None # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"
+ )
+ reply_to_message: bool = False # If true, bot replies quote the original message
+
+
+class FeishuConfig(Base):
+ """Feishu/Lark channel configuration using WebSocket long connection."""
+
+ enabled: bool = False
+ app_id: str = "" # App ID from Feishu Open Platform
+ app_secret: str = "" # App Secret from Feishu Open Platform
+ encrypt_key: str = "" # Encrypt Key for event subscription (optional)
+ verification_token: str = "" # Verification Token for event subscription (optional)
+ allow_from: list[str] = Field(default_factory=list) # Allowed user open_ids
+ react_emoji: str = (
+ "THUMBSUP" # Emoji type for message reactions (e.g. THUMBSUP, OK, DONE, SMILE)
+ )
+
+
+class DingTalkConfig(Base):
+ """DingTalk channel configuration using Stream mode."""
+
+ enabled: bool = False
+ client_id: str = "" # AppKey
+ client_secret: str = "" # AppSecret
+ allow_from: list[str] = Field(default_factory=list) # Allowed staff_ids
+
+
+class DiscordConfig(Base):
+ """Discord channel configuration."""
+
+ enabled: bool = False
+ token: str = "" # Bot token from Discord Developer Portal
+ allow_from: list[str] = Field(default_factory=list) # Allowed user IDs
+ gateway_url: str = "wss://gateway.discord.gg/?v=10&encoding=json"
+ intents: int = 37377 # GUILDS + GUILD_MESSAGES + DIRECT_MESSAGES + MESSAGE_CONTENT
+ group_policy: Literal["mention", "open"] = "mention"
+
+
+class MatrixConfig(Base):
+ """Matrix (Element) channel configuration."""
+
+ enabled: bool = False
+ homeserver: str = "https://matrix.org"
+ access_token: str = ""
+ user_id: str = "" # @bot:matrix.org
+ device_id: str = ""
+ e2ee_enabled: bool = True # Enable Matrix E2EE support (encryption + encrypted room handling).
+ sync_stop_grace_seconds: int = (
+ 2 # Max seconds to wait for sync_forever to stop gracefully before cancellation fallback.
+ )
+ max_media_bytes: int = (
+ 20 * 1024 * 1024
+ ) # Max attachment size accepted for Matrix media handling (inbound + outbound).
+ allow_from: list[str] = Field(default_factory=list)
+ group_policy: Literal["open", "mention", "allowlist"] = "open"
+ group_allow_from: list[str] = Field(default_factory=list)
+ allow_room_mentions: bool = False
+
+
+class EmailConfig(Base):
+ """Email channel configuration (IMAP inbound + SMTP outbound)."""
+
+ enabled: bool = False
+ consent_granted: bool = False # Explicit owner permission to access mailbox data
+
+ # IMAP (receive)
+ imap_host: str = ""
+ imap_port: int = 993
+ imap_username: str = ""
+ imap_password: str = ""
+ imap_mailbox: str = "INBOX"
+ imap_use_ssl: bool = True
+
+ # SMTP (send)
+ smtp_host: str = ""
+ smtp_port: int = 587
+ smtp_username: str = ""
+ smtp_password: str = ""
+ smtp_use_tls: bool = True
+ smtp_use_ssl: bool = False
+ from_address: str = ""
+
+ # Behavior
+ auto_reply_enabled: bool = (
+ True # If false, inbound email is read but no automatic reply is sent
+ )
+ poll_interval_seconds: int = 30
+ mark_seen: bool = True
+ max_body_chars: int = 12000
+ subject_prefix: str = "Re: "
+ allow_from: list[str] = Field(default_factory=list) # Allowed sender email addresses
+
+
+class MochatMentionConfig(Base):
+ """Mochat mention behavior configuration."""
+
+ require_in_groups: bool = False
+
+
+class MochatGroupRule(Base):
+ """Mochat per-group mention requirement."""
+
+ require_mention: bool = False
+
+
+class MochatConfig(Base):
+ """Mochat channel configuration."""
+
+ enabled: bool = False
+ base_url: str = "https://mochat.io"
+ socket_url: str = ""
+ socket_path: str = "/socket.io"
+ socket_disable_msgpack: bool = False
+ socket_reconnect_delay_ms: int = 1000
+ socket_max_reconnect_delay_ms: int = 10000
+ socket_connect_timeout_ms: int = 10000
+ refresh_interval_ms: int = 30000
+ watch_timeout_ms: int = 25000
+ watch_limit: int = 100
+ retry_delay_ms: int = 500
+ max_retry_attempts: int = 0 # 0 means unlimited retries
+ claw_token: str = ""
+ agent_user_id: str = ""
+ sessions: list[str] = Field(default_factory=list)
+ panels: list[str] = Field(default_factory=list)
+ allow_from: list[str] = Field(default_factory=list)
+ mention: MochatMentionConfig = Field(default_factory=MochatMentionConfig)
+ groups: dict[str, MochatGroupRule] = Field(default_factory=dict)
+ reply_delay_mode: str = "non-mention" # off | non-mention
+ reply_delay_ms: int = 120000
+
+
+class SlackDMConfig(Base):
+ """Slack DM policy configuration."""
+
+ enabled: bool = True
+ policy: str = "open" # "open" or "allowlist"
+ allow_from: list[str] = Field(default_factory=list) # Allowed Slack user IDs
+
+
+class SlackConfig(Base):
+ """Slack channel configuration."""
+
+ enabled: bool = False
+ mode: str = "socket" # "socket" supported
+ webhook_path: str = "/slack/events"
+ bot_token: str = "" # xoxb-...
+ app_token: str = "" # xapp-...
+ user_token_read_only: bool = True
+ reply_in_thread: bool = True
+ react_emoji: str = "eyes"
+ allow_from: list[str] = Field(default_factory=list) # Allowed Slack user IDs (sender-level)
+ group_policy: str = "mention" # "mention", "open", "allowlist"
+ group_allow_from: list[str] = Field(default_factory=list) # Allowed channel IDs if allowlist
+ dm: SlackDMConfig = Field(default_factory=SlackDMConfig)
+
+
+class QQConfig(Base):
+ """QQ channel configuration using botpy SDK."""
+
+ enabled: bool = False
+ app_id: str = "" # 机器人 ID (AppID) from q.qq.com
+ secret: str = "" # 机器人密钥 (AppSecret) from q.qq.com
+ allow_from: list[str] = Field(
+ default_factory=list
+ ) # Allowed user openids (empty = public access)
+
+
+
+
+class ChannelsConfig(Base):
+ """Configuration for chat channels."""
+
+ send_progress: bool = True # stream agent's text progress to the channel
+ send_tool_hints: bool = False # stream tool-call hints (e.g. read_file("…"))
+ whatsapp: WhatsAppConfig = Field(default_factory=WhatsAppConfig)
+ telegram: TelegramConfig = Field(default_factory=TelegramConfig)
+ discord: DiscordConfig = Field(default_factory=DiscordConfig)
+ feishu: FeishuConfig = Field(default_factory=FeishuConfig)
+ mochat: MochatConfig = Field(default_factory=MochatConfig)
+ dingtalk: DingTalkConfig = Field(default_factory=DingTalkConfig)
+ email: EmailConfig = Field(default_factory=EmailConfig)
+ slack: SlackConfig = Field(default_factory=SlackConfig)
+ qq: QQConfig = Field(default_factory=QQConfig)
+ matrix: MatrixConfig = Field(default_factory=MatrixConfig)
+
+
+class AgentDefaults(Base):
+ """Default agent configuration."""
+
+ workspace: str = "~/.nanobot/workspace"
+ model: str = "anthropic/claude-opus-4-5"
+ provider: str = (
+ "auto" # Provider name (e.g. "anthropic", "openrouter") or "auto" for auto-detection
+ )
+ max_tokens: int = 8192
+ temperature: float = 0.1
+ max_tool_iterations: int = 40
+ memory_window: int = 100
+ reasoning_effort: str | None = None # low / medium / high — enables LLM thinking mode
+
+
+class AgentsConfig(Base):
+ """Agent configuration."""
+
+ defaults: AgentDefaults = Field(default_factory=AgentDefaults)
+
+
+class ProviderConfig(Base):
+ """LLM provider configuration."""
+
+ api_key: str = ""
+ api_base: str | None = None
+ extra_headers: dict[str, str] | None = None # Custom headers (e.g. APP-Code for AiHubMix)
+
+
+class ProvidersConfig(Base):
+ """Configuration for LLM providers."""
+
+ custom: ProviderConfig = Field(default_factory=ProviderConfig) # Any OpenAI-compatible endpoint
+ azure_openai: ProviderConfig = Field(default_factory=ProviderConfig) # Azure OpenAI (model = deployment name)
+ anthropic: ProviderConfig = Field(default_factory=ProviderConfig)
+ openai: ProviderConfig = Field(default_factory=ProviderConfig)
+ openrouter: ProviderConfig = Field(default_factory=ProviderConfig)
+ deepseek: ProviderConfig = Field(default_factory=ProviderConfig)
+ groq: ProviderConfig = Field(default_factory=ProviderConfig)
+ zhipu: ProviderConfig = Field(default_factory=ProviderConfig)
+ dashscope: ProviderConfig = Field(default_factory=ProviderConfig) # 阿里云通义千问
+ vllm: ProviderConfig = Field(default_factory=ProviderConfig)
+ gemini: ProviderConfig = Field(default_factory=ProviderConfig)
+ moonshot: ProviderConfig = Field(default_factory=ProviderConfig)
+ minimax: ProviderConfig = Field(default_factory=ProviderConfig)
+ aihubmix: ProviderConfig = Field(default_factory=ProviderConfig) # AiHubMix API gateway
+ siliconflow: ProviderConfig = Field(default_factory=ProviderConfig) # SiliconFlow (硅基流动)
+ volcengine: ProviderConfig = Field(default_factory=ProviderConfig) # VolcEngine (火山引擎)
+ openai_codex: ProviderConfig = Field(default_factory=ProviderConfig) # OpenAI Codex (OAuth)
+ github_copilot: ProviderConfig = Field(default_factory=ProviderConfig) # Github Copilot (OAuth)
+
+
+class HeartbeatConfig(Base):
+ """Heartbeat service configuration."""
+
+ enabled: bool = True
+ interval_s: int = 30 * 60 # 30 minutes
+
+
+class GatewayConfig(Base):
+ """Gateway/server configuration."""
+
+ host: str = "0.0.0.0"
+ port: int = 18790
+ heartbeat: HeartbeatConfig = Field(default_factory=HeartbeatConfig)
+
+
+class WebSearchConfig(Base):
+ """Web search tool configuration."""
+
+ api_key: str = "" # Brave Search API key
+ max_results: int = 5
+
+
+class WebToolsConfig(Base):
+ """Web tools configuration."""
+
+ proxy: str | None = (
+ None # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"
+ )
+ search: WebSearchConfig = Field(default_factory=WebSearchConfig)
+
+
+class ExecToolConfig(Base):
+ """Shell exec tool configuration."""
+
+ timeout: int = 60
+ path_append: str = ""
+
+
+class MCPServerConfig(Base):
+ """MCP server connection configuration (stdio or HTTP)."""
+
+ type: Literal["stdio", "sse", "streamableHttp"] | None = None # auto-detected if omitted
+ command: str = "" # Stdio: command to run (e.g. "npx")
+ args: list[str] = Field(default_factory=list) # Stdio: command arguments
+ env: dict[str, str] = Field(default_factory=dict) # Stdio: extra env vars
+ url: str = "" # HTTP/SSE: endpoint URL
+ headers: dict[str, str] = Field(default_factory=dict) # HTTP/SSE: custom headers
+ tool_timeout: int = 30 # seconds before a tool call is cancelled
+
+
+class ToolsConfig(Base):
+ """Tools configuration."""
+
+ web: WebToolsConfig = Field(default_factory=WebToolsConfig)
+ exec: ExecToolConfig = Field(default_factory=ExecToolConfig)
+ restrict_to_workspace: bool = False # If true, restrict all tool access to workspace directory
+ mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+
+class Config(BaseSettings):
+ """Root configuration for nanobot."""
+
+ agents: AgentsConfig = Field(default_factory=AgentsConfig)
+ channels: ChannelsConfig = Field(default_factory=ChannelsConfig)
+ providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
+ gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+ tools: ToolsConfig = Field(default_factory=ToolsConfig)
+
+ @property
+ def workspace_path(self) -> Path:
+ """Get expanded workspace path."""
+ return Path(self.agents.defaults.workspace).expanduser()
+
+ def _match_provider(
+ self, model: str | None = None
+ ) -> tuple["ProviderConfig | None", str | None]:
+ """Match provider config and its registry name. Returns (config, spec_name)."""
+ from nanobot.providers.registry import PROVIDERS
+
+ forced = self.agents.defaults.provider
+ if forced != "auto":
+ p = getattr(self.providers, forced, None)
+ return (p, forced) if p else (None, None)
+
+ model_lower = (model or self.agents.defaults.model).lower()
+ model_normalized = model_lower.replace("-", "_")
+ model_prefix = model_lower.split("/", 1)[0] if "/" in model_lower else ""
+ normalized_prefix = model_prefix.replace("-", "_")
+
+ def _kw_matches(kw: str) -> bool:
+ kw = kw.lower()
+ return kw in model_lower or kw.replace("-", "_") in model_normalized
+
+ # Explicit provider prefix wins — prevents `github-copilot/...codex` matching openai_codex.
+ for spec in PROVIDERS:
+ p = getattr(self.providers, spec.name, None)
+ if p and model_prefix and normalized_prefix == spec.name:
+ if spec.is_oauth or p.api_key:
+ return p, spec.name
+
+ # Match by keyword (order follows PROVIDERS registry)
+ for spec in PROVIDERS:
+ p = getattr(self.providers, spec.name, None)
+ if p and any(_kw_matches(kw) for kw in spec.keywords):
+ if spec.is_oauth or p.api_key:
+ return p, spec.name
+
+ # Fallback: gateways first, then others (follows registry order)
+ # OAuth providers are NOT valid fallbacks — they require explicit model selection
+ for spec in PROVIDERS:
+ if spec.is_oauth:
+ continue
+ p = getattr(self.providers, spec.name, None)
+ if p and p.api_key:
+ return p, spec.name
+ return None, None
+
+ def get_provider(self, model: str | None = None) -> ProviderConfig | None:
+ """Get matched provider config (api_key, api_base, extra_headers). Falls back to first available."""
+ p, _ = self._match_provider(model)
+ return p
+
+ def get_provider_name(self, model: str | None = None) -> str | None:
+ """Get the registry name of the matched provider (e.g. "deepseek", "openrouter")."""
+ _, name = self._match_provider(model)
+ return name
+
+ def get_api_key(self, model: str | None = None) -> str | None:
+ """Get API key for the given model. Falls back to first available key."""
+ p = self.get_provider(model)
+ return p.api_key if p else None
+
+ def get_api_base(self, model: str | None = None) -> str | None:
+ """Get API base URL for the given model. Applies default URLs for known gateways."""
+ from nanobot.providers.registry import find_by_name
+
+ p, name = self._match_provider(model)
+ if p and p.api_base:
+ return p.api_base
+ # Only gateways get a default api_base here. Standard providers
+ # (like Moonshot) set their base URL via env vars in _setup_env
+ # to avoid polluting the global litellm.api_base.
+ if name:
+ spec = find_by_name(name)
+ if spec and spec.is_gateway and spec.default_api_base:
+ return spec.default_api_base
+ return None
+
+ model_config = ConfigDict(env_prefix="NANOBOT_", env_nested_delimiter="__")
diff --git a/nanobot/nanobot/cron/__init__.py b/nanobot/nanobot/cron/__init__.py
new file mode 100644
index 0000000..a9d4cad
--- /dev/null
+++ b/nanobot/nanobot/cron/__init__.py
@@ -0,0 +1,6 @@
+"""Cron service for scheduled agent tasks."""
+
+from nanobot.cron.service import CronService
+from nanobot.cron.types import CronJob, CronSchedule
+
+__all__ = ["CronService", "CronJob", "CronSchedule"]
diff --git a/nanobot/nanobot/cron/service.py b/nanobot/nanobot/cron/service.py
new file mode 100644
index 0000000..1ed71f0
--- /dev/null
+++ b/nanobot/nanobot/cron/service.py
@@ -0,0 +1,376 @@
+"""Cron service for scheduling agent tasks."""
+
+import asyncio
+import json
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Coroutine
+
+from loguru import logger
+
+from nanobot.cron.types import CronJob, CronJobState, CronPayload, CronSchedule, CronStore
+
+
+def _now_ms() -> int:
+ return int(time.time() * 1000)
+
+
+def _compute_next_run(schedule: CronSchedule, now_ms: int) -> int | None:
+ """Compute next run time in ms."""
+ if schedule.kind == "at":
+ return schedule.at_ms if schedule.at_ms and schedule.at_ms > now_ms else None
+
+ if schedule.kind == "every":
+ if not schedule.every_ms or schedule.every_ms <= 0:
+ return None
+ # Next interval from now
+ return now_ms + schedule.every_ms
+
+ if schedule.kind == "cron" and schedule.expr:
+ try:
+ from zoneinfo import ZoneInfo
+
+ from croniter import croniter
+ # Use caller-provided reference time for deterministic scheduling
+ base_time = now_ms / 1000
+ tz = ZoneInfo(schedule.tz) if schedule.tz else datetime.now().astimezone().tzinfo
+ base_dt = datetime.fromtimestamp(base_time, tz=tz)
+ cron = croniter(schedule.expr, base_dt)
+ next_dt = cron.get_next(datetime)
+ return int(next_dt.timestamp() * 1000)
+ except Exception:
+ return None
+
+ return None
+
+
+def _validate_schedule_for_add(schedule: CronSchedule) -> None:
+ """Validate schedule fields that would otherwise create non-runnable jobs."""
+ if schedule.tz and schedule.kind != "cron":
+ raise ValueError("tz can only be used with cron schedules")
+
+ if schedule.kind == "cron" and schedule.tz:
+ try:
+ from zoneinfo import ZoneInfo
+
+ ZoneInfo(schedule.tz)
+ except Exception:
+ raise ValueError(f"unknown timezone '{schedule.tz}'") from None
+
+
+class CronService:
+ """Service for managing and executing scheduled jobs."""
+
+ def __init__(
+ self,
+ store_path: Path,
+ on_job: Callable[[CronJob], Coroutine[Any, Any, str | None]] | None = None
+ ):
+ self.store_path = store_path
+ self.on_job = on_job
+ self._store: CronStore | None = None
+ self._last_mtime: float = 0.0
+ self._timer_task: asyncio.Task | None = None
+ self._running = False
+
+ def _load_store(self) -> CronStore:
+ """Load jobs from disk. Reloads automatically if file was modified externally."""
+ if self._store and self.store_path.exists():
+ mtime = self.store_path.stat().st_mtime
+ if mtime != self._last_mtime:
+ logger.info("Cron: jobs.json modified externally, reloading")
+ self._store = None
+ if self._store:
+ return self._store
+
+ if self.store_path.exists():
+ try:
+ data = json.loads(self.store_path.read_text(encoding="utf-8"))
+ jobs = []
+ for j in data.get("jobs", []):
+ jobs.append(CronJob(
+ id=j["id"],
+ name=j["name"],
+ enabled=j.get("enabled", True),
+ schedule=CronSchedule(
+ kind=j["schedule"]["kind"],
+ at_ms=j["schedule"].get("atMs"),
+ every_ms=j["schedule"].get("everyMs"),
+ expr=j["schedule"].get("expr"),
+ tz=j["schedule"].get("tz"),
+ ),
+ payload=CronPayload(
+ kind=j["payload"].get("kind", "agent_turn"),
+ message=j["payload"].get("message", ""),
+ deliver=j["payload"].get("deliver", False),
+ channel=j["payload"].get("channel"),
+ to=j["payload"].get("to"),
+ ),
+ state=CronJobState(
+ next_run_at_ms=j.get("state", {}).get("nextRunAtMs"),
+ last_run_at_ms=j.get("state", {}).get("lastRunAtMs"),
+ last_status=j.get("state", {}).get("lastStatus"),
+ last_error=j.get("state", {}).get("lastError"),
+ ),
+ created_at_ms=j.get("createdAtMs", 0),
+ updated_at_ms=j.get("updatedAtMs", 0),
+ delete_after_run=j.get("deleteAfterRun", False),
+ ))
+ self._store = CronStore(jobs=jobs)
+ except Exception as e:
+ logger.warning("Failed to load cron store: {}", e)
+ self._store = CronStore()
+ else:
+ self._store = CronStore()
+
+ return self._store
+
+ def _save_store(self) -> None:
+ """Save jobs to disk."""
+ if not self._store:
+ return
+
+ self.store_path.parent.mkdir(parents=True, exist_ok=True)
+
+ data = {
+ "version": self._store.version,
+ "jobs": [
+ {
+ "id": j.id,
+ "name": j.name,
+ "enabled": j.enabled,
+ "schedule": {
+ "kind": j.schedule.kind,
+ "atMs": j.schedule.at_ms,
+ "everyMs": j.schedule.every_ms,
+ "expr": j.schedule.expr,
+ "tz": j.schedule.tz,
+ },
+ "payload": {
+ "kind": j.payload.kind,
+ "message": j.payload.message,
+ "deliver": j.payload.deliver,
+ "channel": j.payload.channel,
+ "to": j.payload.to,
+ },
+ "state": {
+ "nextRunAtMs": j.state.next_run_at_ms,
+ "lastRunAtMs": j.state.last_run_at_ms,
+ "lastStatus": j.state.last_status,
+ "lastError": j.state.last_error,
+ },
+ "createdAtMs": j.created_at_ms,
+ "updatedAtMs": j.updated_at_ms,
+ "deleteAfterRun": j.delete_after_run,
+ }
+ for j in self._store.jobs
+ ]
+ }
+
+ self.store_path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+ self._last_mtime = self.store_path.stat().st_mtime
+
+ async def start(self) -> None:
+ """Start the cron service."""
+ self._running = True
+ self._load_store()
+ self._recompute_next_runs()
+ self._save_store()
+ self._arm_timer()
+ logger.info("Cron service started with {} jobs", len(self._store.jobs if self._store else []))
+
+ def stop(self) -> None:
+ """Stop the cron service."""
+ self._running = False
+ if self._timer_task:
+ self._timer_task.cancel()
+ self._timer_task = None
+
+ def _recompute_next_runs(self) -> None:
+ """Recompute next run times for all enabled jobs."""
+ if not self._store:
+ return
+ now = _now_ms()
+ for job in self._store.jobs:
+ if job.enabled:
+ job.state.next_run_at_ms = _compute_next_run(job.schedule, now)
+
+ def _get_next_wake_ms(self) -> int | None:
+ """Get the earliest next run time across all jobs."""
+ if not self._store:
+ return None
+ times = [j.state.next_run_at_ms for j in self._store.jobs
+ if j.enabled and j.state.next_run_at_ms]
+ return min(times) if times else None
+
+ def _arm_timer(self) -> None:
+ """Schedule the next timer tick."""
+ if self._timer_task:
+ self._timer_task.cancel()
+
+ next_wake = self._get_next_wake_ms()
+ if not next_wake or not self._running:
+ return
+
+ delay_ms = max(0, next_wake - _now_ms())
+ delay_s = delay_ms / 1000
+
+ async def tick():
+ await asyncio.sleep(delay_s)
+ if self._running:
+ await self._on_timer()
+
+ self._timer_task = asyncio.create_task(tick())
+
+ async def _on_timer(self) -> None:
+ """Handle timer tick - run due jobs."""
+ self._load_store()
+ if not self._store:
+ return
+
+ now = _now_ms()
+ due_jobs = [
+ j for j in self._store.jobs
+ if j.enabled and j.state.next_run_at_ms and now >= j.state.next_run_at_ms
+ ]
+
+ for job in due_jobs:
+ await self._execute_job(job)
+
+ self._save_store()
+ self._arm_timer()
+
+ async def _execute_job(self, job: CronJob) -> None:
+ """Execute a single job."""
+ start_ms = _now_ms()
+ logger.info("Cron: executing job '{}' ({})", job.name, job.id)
+
+ try:
+ response = None
+ if self.on_job:
+ response = await self.on_job(job)
+
+ job.state.last_status = "ok"
+ job.state.last_error = None
+ logger.info("Cron: job '{}' completed", job.name)
+
+ except Exception as e:
+ job.state.last_status = "error"
+ job.state.last_error = str(e)
+ logger.error("Cron: job '{}' failed: {}", job.name, e)
+
+ job.state.last_run_at_ms = start_ms
+ job.updated_at_ms = _now_ms()
+
+ # Handle one-shot jobs
+ if job.schedule.kind == "at":
+ if job.delete_after_run:
+ self._store.jobs = [j for j in self._store.jobs if j.id != job.id]
+ else:
+ job.enabled = False
+ job.state.next_run_at_ms = None
+ else:
+ # Compute next run
+ job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+
+ # ========== Public API ==========
+
+ def list_jobs(self, include_disabled: bool = False) -> list[CronJob]:
+ """List all jobs."""
+ store = self._load_store()
+ jobs = store.jobs if include_disabled else [j for j in store.jobs if j.enabled]
+ return sorted(jobs, key=lambda j: j.state.next_run_at_ms or float('inf'))
+
+ def add_job(
+ self,
+ name: str,
+ schedule: CronSchedule,
+ message: str,
+ deliver: bool = False,
+ channel: str | None = None,
+ to: str | None = None,
+ delete_after_run: bool = False,
+ ) -> CronJob:
+ """Add a new job."""
+ store = self._load_store()
+ _validate_schedule_for_add(schedule)
+ now = _now_ms()
+
+ job = CronJob(
+ id=str(uuid.uuid4())[:8],
+ name=name,
+ enabled=True,
+ schedule=schedule,
+ payload=CronPayload(
+ kind="agent_turn",
+ message=message,
+ deliver=deliver,
+ channel=channel,
+ to=to,
+ ),
+ state=CronJobState(next_run_at_ms=_compute_next_run(schedule, now)),
+ created_at_ms=now,
+ updated_at_ms=now,
+ delete_after_run=delete_after_run,
+ )
+
+ store.jobs.append(job)
+ self._save_store()
+ self._arm_timer()
+
+ logger.info("Cron: added job '{}' ({})", name, job.id)
+ return job
+
+ def remove_job(self, job_id: str) -> bool:
+ """Remove a job by ID."""
+ store = self._load_store()
+ before = len(store.jobs)
+ store.jobs = [j for j in store.jobs if j.id != job_id]
+ removed = len(store.jobs) < before
+
+ if removed:
+ self._save_store()
+ self._arm_timer()
+ logger.info("Cron: removed job {}", job_id)
+
+ return removed
+
+ def enable_job(self, job_id: str, enabled: bool = True) -> CronJob | None:
+ """Enable or disable a job."""
+ store = self._load_store()
+ for job in store.jobs:
+ if job.id == job_id:
+ job.enabled = enabled
+ job.updated_at_ms = _now_ms()
+ if enabled:
+ job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+ else:
+ job.state.next_run_at_ms = None
+ self._save_store()
+ self._arm_timer()
+ return job
+ return None
+
+ async def run_job(self, job_id: str, force: bool = False) -> bool:
+ """Manually run a job."""
+ store = self._load_store()
+ for job in store.jobs:
+ if job.id == job_id:
+ if not force and not job.enabled:
+ return False
+ await self._execute_job(job)
+ self._save_store()
+ self._arm_timer()
+ return True
+ return False
+
+ def status(self) -> dict:
+ """Get service status."""
+ store = self._load_store()
+ return {
+ "enabled": self._running,
+ "jobs": len(store.jobs),
+ "next_wake_at_ms": self._get_next_wake_ms(),
+ }
diff --git a/nanobot/nanobot/cron/types.py b/nanobot/nanobot/cron/types.py
new file mode 100644
index 0000000..2b42060
--- /dev/null
+++ b/nanobot/nanobot/cron/types.py
@@ -0,0 +1,59 @@
+"""Cron types."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class CronSchedule:
+ """Schedule definition for a cron job."""
+ kind: Literal["at", "every", "cron"]
+ # For "at": timestamp in ms
+ at_ms: int | None = None
+ # For "every": interval in ms
+ every_ms: int | None = None
+ # For "cron": cron expression (e.g. "0 9 * * *")
+ expr: str | None = None
+ # Timezone for cron expressions
+ tz: str | None = None
+
+
+@dataclass
+class CronPayload:
+ """What to do when the job runs."""
+ kind: Literal["system_event", "agent_turn"] = "agent_turn"
+ message: str = ""
+ # Deliver response to channel
+ deliver: bool = False
+ channel: str | None = None # e.g. "whatsapp"
+ to: str | None = None # e.g. phone number
+
+
+@dataclass
+class CronJobState:
+ """Runtime state of a job."""
+ next_run_at_ms: int | None = None
+ last_run_at_ms: int | None = None
+ last_status: Literal["ok", "error", "skipped"] | None = None
+ last_error: str | None = None
+
+
+@dataclass
+class CronJob:
+ """A scheduled job."""
+ id: str
+ name: str
+ enabled: bool = True
+ schedule: CronSchedule = field(default_factory=lambda: CronSchedule(kind="every"))
+ payload: CronPayload = field(default_factory=CronPayload)
+ state: CronJobState = field(default_factory=CronJobState)
+ created_at_ms: int = 0
+ updated_at_ms: int = 0
+ delete_after_run: bool = False
+
+
+@dataclass
+class CronStore:
+ """Persistent store for cron jobs."""
+ version: int = 1
+ jobs: list[CronJob] = field(default_factory=list)
diff --git a/nanobot/nanobot/heartbeat/__init__.py b/nanobot/nanobot/heartbeat/__init__.py
new file mode 100644
index 0000000..2ecd879
--- /dev/null
+++ b/nanobot/nanobot/heartbeat/__init__.py
@@ -0,0 +1,5 @@
+"""Heartbeat service for periodic agent wake-ups."""
+
+from nanobot.heartbeat.service import HeartbeatService
+
+__all__ = ["HeartbeatService"]
diff --git a/nanobot/nanobot/heartbeat/service.py b/nanobot/nanobot/heartbeat/service.py
new file mode 100644
index 0000000..e534017
--- /dev/null
+++ b/nanobot/nanobot/heartbeat/service.py
@@ -0,0 +1,173 @@
+"""Heartbeat service - periodic agent wake-up to check for tasks."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+from loguru import logger
+
+if TYPE_CHECKING:
+ from nanobot.providers.base import LLMProvider
+
+_HEARTBEAT_TOOL = [
+ {
+ "type": "function",
+ "function": {
+ "name": "heartbeat",
+ "description": "Report heartbeat decision after reviewing tasks.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "action": {
+ "type": "string",
+ "enum": ["skip", "run"],
+ "description": "skip = nothing to do, run = has active tasks",
+ },
+ "tasks": {
+ "type": "string",
+ "description": "Natural-language summary of active tasks (required for run)",
+ },
+ },
+ "required": ["action"],
+ },
+ },
+ }
+]
+
+
+class HeartbeatService:
+ """
+ Periodic heartbeat service that wakes the agent to check for tasks.
+
+ Phase 1 (decision): reads HEARTBEAT.md and asks the LLM — via a virtual
+ tool call — whether there are active tasks. This avoids free-text parsing
+ and the unreliable HEARTBEAT_OK token.
+
+ Phase 2 (execution): only triggered when Phase 1 returns ``run``. The
+ ``on_execute`` callback runs the task through the full agent loop and
+ returns the result to deliver.
+ """
+
+ def __init__(
+ self,
+ workspace: Path,
+ provider: LLMProvider,
+ model: str,
+ on_execute: Callable[[str], Coroutine[Any, Any, str]] | None = None,
+ on_notify: Callable[[str], Coroutine[Any, Any, None]] | None = None,
+ interval_s: int = 30 * 60,
+ enabled: bool = True,
+ ):
+ self.workspace = workspace
+ self.provider = provider
+ self.model = model
+ self.on_execute = on_execute
+ self.on_notify = on_notify
+ self.interval_s = interval_s
+ self.enabled = enabled
+ self._running = False
+ self._task: asyncio.Task | None = None
+
+ @property
+ def heartbeat_file(self) -> Path:
+ return self.workspace / "HEARTBEAT.md"
+
+ def _read_heartbeat_file(self) -> str | None:
+ if self.heartbeat_file.exists():
+ try:
+ return self.heartbeat_file.read_text(encoding="utf-8")
+ except Exception:
+ return None
+ return None
+
+ async def _decide(self, content: str) -> tuple[str, str]:
+ """Phase 1: ask LLM to decide skip/run via virtual tool call.
+
+ Returns (action, tasks) where action is 'skip' or 'run'.
+ """
+ response = await self.provider.chat(
+ messages=[
+ {"role": "system", "content": "You are a heartbeat agent. Call the heartbeat tool to report your decision."},
+ {"role": "user", "content": (
+ "Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n"
+ f"{content}"
+ )},
+ ],
+ tools=_HEARTBEAT_TOOL,
+ model=self.model,
+ )
+
+ if not response.has_tool_calls:
+ return "skip", ""
+
+ args = response.tool_calls[0].arguments
+ return args.get("action", "skip"), args.get("tasks", "")
+
+ async def start(self) -> None:
+ """Start the heartbeat service."""
+ if not self.enabled:
+ logger.info("Heartbeat disabled")
+ return
+ if self._running:
+ logger.warning("Heartbeat already running")
+ return
+
+ self._running = True
+ self._task = asyncio.create_task(self._run_loop())
+ logger.info("Heartbeat started (every {}s)", self.interval_s)
+
+ def stop(self) -> None:
+ """Stop the heartbeat service."""
+ self._running = False
+ if self._task:
+ self._task.cancel()
+ self._task = None
+
+ async def _run_loop(self) -> None:
+ """Main heartbeat loop."""
+ while self._running:
+ try:
+ await asyncio.sleep(self.interval_s)
+ if self._running:
+ await self._tick()
+ except asyncio.CancelledError:
+ break
+ except Exception as e:
+ logger.error("Heartbeat error: {}", e)
+
+ async def _tick(self) -> None:
+ """Execute a single heartbeat tick."""
+ content = self._read_heartbeat_file()
+ if not content:
+ logger.debug("Heartbeat: HEARTBEAT.md missing or empty")
+ return
+
+ logger.info("Heartbeat: checking for tasks...")
+
+ try:
+ action, tasks = await self._decide(content)
+
+ if action != "run":
+ logger.info("Heartbeat: OK (nothing to report)")
+ return
+
+ logger.info("Heartbeat: tasks found, executing...")
+ if self.on_execute:
+ response = await self.on_execute(tasks)
+ if response and self.on_notify:
+ logger.info("Heartbeat: completed, delivering response")
+ await self.on_notify(response)
+ except Exception:
+ logger.exception("Heartbeat execution failed")
+
+ async def trigger_now(self) -> str | None:
+ """Manually trigger a heartbeat."""
+ content = self._read_heartbeat_file()
+ if not content:
+ return None
+ action, tasks = await self._decide(content)
+ if action != "run" or not self.on_execute:
+ return None
+ return await self.on_execute(tasks)
diff --git a/nanobot/nanobot/providers/__init__.py b/nanobot/nanobot/providers/__init__.py
new file mode 100644
index 0000000..5bd06f9
--- /dev/null
+++ b/nanobot/nanobot/providers/__init__.py
@@ -0,0 +1,8 @@
+"""LLM provider abstraction module."""
+
+from nanobot.providers.base import LLMProvider, LLMResponse
+from nanobot.providers.litellm_provider import LiteLLMProvider
+from nanobot.providers.openai_codex_provider import OpenAICodexProvider
+from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+
+__all__ = ["LLMProvider", "LLMResponse", "LiteLLMProvider", "OpenAICodexProvider", "AzureOpenAIProvider"]
diff --git a/nanobot/nanobot/providers/azure_openai_provider.py b/nanobot/nanobot/providers/azure_openai_provider.py
new file mode 100644
index 0000000..bd79b00
--- /dev/null
+++ b/nanobot/nanobot/providers/azure_openai_provider.py
@@ -0,0 +1,210 @@
+"""Azure OpenAI provider implementation with API version 2024-10-21."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+import json_repair
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+_AZURE_MSG_KEYS = frozenset({"role", "content", "tool_calls", "tool_call_id", "name"})
+
+
+class AzureOpenAIProvider(LLMProvider):
+ """
+ Azure OpenAI provider with API version 2024-10-21 compliance.
+
+ Features:
+ - Hardcoded API version 2024-10-21
+ - Uses model field as Azure deployment name in URL path
+ - Uses api-key header instead of Authorization Bearer
+ - Uses max_completion_tokens instead of max_tokens
+ - Direct HTTP calls, bypasses LiteLLM
+ """
+
+ def __init__(
+ self,
+ api_key: str = "",
+ api_base: str = "",
+ default_model: str = "gpt-5.2-chat",
+ ):
+ super().__init__(api_key, api_base)
+ self.default_model = default_model
+ self.api_version = "2024-10-21"
+
+ # Validate required parameters
+ if not api_key:
+ raise ValueError("Azure OpenAI api_key is required")
+ if not api_base:
+ raise ValueError("Azure OpenAI api_base is required")
+
+ # Ensure api_base ends with /
+ if not api_base.endswith('/'):
+ api_base += '/'
+ self.api_base = api_base
+
+ def _build_chat_url(self, deployment_name: str) -> str:
+ """Build the Azure OpenAI chat completions URL."""
+ # Azure OpenAI URL format:
+ # https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version={version}
+ base_url = self.api_base
+ if not base_url.endswith('/'):
+ base_url += '/'
+
+ url = urljoin(
+ base_url,
+ f"openai/deployments/{deployment_name}/chat/completions"
+ )
+ return f"{url}?api-version={self.api_version}"
+
+ def _build_headers(self) -> dict[str, str]:
+ """Build headers for Azure OpenAI API with api-key header."""
+ return {
+ "Content-Type": "application/json",
+ "api-key": self.api_key, # Azure OpenAI uses api-key header, not Authorization
+ "x-session-affinity": uuid.uuid4().hex, # For cache locality
+ }
+
+ @staticmethod
+ def _supports_temperature(
+ deployment_name: str,
+ reasoning_effort: str | None = None,
+ ) -> bool:
+ """Return True when temperature is likely supported for this deployment."""
+ if reasoning_effort:
+ return False
+ name = deployment_name.lower()
+ return not any(token in name for token in ("gpt-5", "o1", "o3", "o4"))
+
+ def _prepare_request_payload(
+ self,
+ deployment_name: str,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None = None,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+ reasoning_effort: str | None = None,
+ ) -> dict[str, Any]:
+ """Prepare the request payload with Azure OpenAI 2024-10-21 compliance."""
+ payload: dict[str, Any] = {
+ "messages": self._sanitize_request_messages(
+ self._sanitize_empty_content(messages),
+ _AZURE_MSG_KEYS,
+ ),
+ "max_completion_tokens": max(1, max_tokens), # Azure API 2024-10-21 uses max_completion_tokens
+ }
+
+ if self._supports_temperature(deployment_name, reasoning_effort):
+ payload["temperature"] = temperature
+
+ if reasoning_effort:
+ payload["reasoning_effort"] = reasoning_effort
+
+ if tools:
+ payload["tools"] = tools
+ payload["tool_choice"] = "auto"
+
+ return payload
+
+ async def chat(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None = None,
+ model: str | None = None,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+ reasoning_effort: str | None = None,
+ ) -> LLMResponse:
+ """
+ Send a chat completion request to Azure OpenAI.
+
+ Args:
+ messages: List of message dicts with 'role' and 'content'.
+ tools: Optional list of tool definitions in OpenAI format.
+ model: Model identifier (used as deployment name).
+ max_tokens: Maximum tokens in response (mapped to max_completion_tokens).
+ temperature: Sampling temperature.
+ reasoning_effort: Optional reasoning effort parameter.
+
+ Returns:
+ LLMResponse with content and/or tool calls.
+ """
+ deployment_name = model or self.default_model
+ url = self._build_chat_url(deployment_name)
+ headers = self._build_headers()
+ payload = self._prepare_request_payload(
+ deployment_name, messages, tools, max_tokens, temperature, reasoning_effort
+ )
+
+ try:
+ async with httpx.AsyncClient(timeout=60.0, verify=True) as client:
+ response = await client.post(url, headers=headers, json=payload)
+ if response.status_code != 200:
+ return LLMResponse(
+ content=f"Azure OpenAI API Error {response.status_code}: {response.text}",
+ finish_reason="error",
+ )
+
+ response_data = response.json()
+ return self._parse_response(response_data)
+
+ except Exception as e:
+ return LLMResponse(
+ content=f"Error calling Azure OpenAI: {repr(e)}",
+ finish_reason="error",
+ )
+
+ def _parse_response(self, response: dict[str, Any]) -> LLMResponse:
+ """Parse Azure OpenAI response into our standard format."""
+ try:
+ choice = response["choices"][0]
+ message = choice["message"]
+
+ tool_calls = []
+ if message.get("tool_calls"):
+ for tc in message["tool_calls"]:
+ # Parse arguments from JSON string if needed
+ args = tc["function"]["arguments"]
+ if isinstance(args, str):
+ args = json_repair.loads(args)
+
+ tool_calls.append(
+ ToolCallRequest(
+ id=tc["id"],
+ name=tc["function"]["name"],
+ arguments=args,
+ )
+ )
+
+ usage = {}
+ if response.get("usage"):
+ usage_data = response["usage"]
+ usage = {
+ "prompt_tokens": usage_data.get("prompt_tokens", 0),
+ "completion_tokens": usage_data.get("completion_tokens", 0),
+ "total_tokens": usage_data.get("total_tokens", 0),
+ }
+
+ reasoning_content = message.get("reasoning_content") or None
+
+ return LLMResponse(
+ content=message.get("content"),
+ tool_calls=tool_calls,
+ finish_reason=choice.get("finish_reason", "stop"),
+ usage=usage,
+ reasoning_content=reasoning_content,
+ )
+
+ except (KeyError, IndexError) as e:
+ return LLMResponse(
+ content=f"Error parsing Azure OpenAI response: {str(e)}",
+ finish_reason="error",
+ )
+
+ def get_default_model(self) -> str:
+ """Get the default model (also used as default deployment name)."""
+ return self.default_model
\ No newline at end of file
diff --git a/nanobot/nanobot/providers/base.py b/nanobot/nanobot/providers/base.py
new file mode 100644
index 0000000..0f73544
--- /dev/null
+++ b/nanobot/nanobot/providers/base.py
@@ -0,0 +1,132 @@
+"""Base LLM provider interface."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolCallRequest:
+ """A tool call request from the LLM."""
+ id: str
+ name: str
+ arguments: dict[str, Any]
+
+
+@dataclass
+class LLMResponse:
+ """Response from an LLM provider."""
+ content: str | None
+ tool_calls: list[ToolCallRequest] = field(default_factory=list)
+ finish_reason: str = "stop"
+ usage: dict[str, int] = field(default_factory=dict)
+ reasoning_content: str | None = None # Kimi, DeepSeek-R1 etc.
+ thinking_blocks: list[dict] | None = None # Anthropic extended thinking
+
+ @property
+ def has_tool_calls(self) -> bool:
+ """Check if response contains tool calls."""
+ return len(self.tool_calls) > 0
+
+
+class LLMProvider(ABC):
+ """
+ Abstract base class for LLM providers.
+
+ Implementations should handle the specifics of each provider's API
+ while maintaining a consistent interface.
+ """
+
+ def __init__(self, api_key: str | None = None, api_base: str | None = None):
+ self.api_key = api_key
+ self.api_base = api_base
+
+ @staticmethod
+ def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """Replace empty text content that causes provider 400 errors.
+
+ Empty content can appear when MCP tools return nothing. Most providers
+ reject empty-string content or empty text blocks in list content.
+ """
+ result: list[dict[str, Any]] = []
+ for msg in messages:
+ content = msg.get("content")
+
+ if isinstance(content, str) and not content:
+ clean = dict(msg)
+ clean["content"] = None if (msg.get("role") == "assistant" and msg.get("tool_calls")) else "(empty)"
+ result.append(clean)
+ continue
+
+ if isinstance(content, list):
+ filtered = [
+ item for item in content
+ if not (
+ isinstance(item, dict)
+ and item.get("type") in ("text", "input_text", "output_text")
+ and not item.get("text")
+ )
+ ]
+ if len(filtered) != len(content):
+ clean = dict(msg)
+ if filtered:
+ clean["content"] = filtered
+ elif msg.get("role") == "assistant" and msg.get("tool_calls"):
+ clean["content"] = None
+ else:
+ clean["content"] = "(empty)"
+ result.append(clean)
+ continue
+
+ if isinstance(content, dict):
+ clean = dict(msg)
+ clean["content"] = [content]
+ result.append(clean)
+ continue
+
+ result.append(msg)
+ return result
+
+ @staticmethod
+ def _sanitize_request_messages(
+ messages: list[dict[str, Any]],
+ allowed_keys: frozenset[str],
+ ) -> list[dict[str, Any]]:
+ """Keep only provider-safe message keys and normalize assistant content."""
+ sanitized = []
+ for msg in messages:
+ clean = {k: v for k, v in msg.items() if k in allowed_keys}
+ if clean.get("role") == "assistant" and "content" not in clean:
+ clean["content"] = None
+ sanitized.append(clean)
+ return sanitized
+
+ @abstractmethod
+ async def chat(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None = None,
+ model: str | None = None,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+ reasoning_effort: str | None = None,
+ ) -> LLMResponse:
+ """
+ Send a chat completion request.
+
+ Args:
+ messages: List of message dicts with 'role' and 'content'.
+ tools: Optional list of tool definitions.
+ model: Model identifier (provider-specific).
+ max_tokens: Maximum tokens in response.
+ temperature: Sampling temperature.
+
+ Returns:
+ LLMResponse with content and/or tool calls.
+ """
+ pass
+
+ @abstractmethod
+ def get_default_model(self) -> str:
+ """Get the default model for this provider."""
+ pass
diff --git a/nanobot/nanobot/providers/custom_provider.py b/nanobot/nanobot/providers/custom_provider.py
new file mode 100644
index 0000000..66df734
--- /dev/null
+++ b/nanobot/nanobot/providers/custom_provider.py
@@ -0,0 +1,61 @@
+"""Direct OpenAI-compatible provider — bypasses LiteLLM."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import json_repair
+from openai import AsyncOpenAI
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+class CustomProvider(LLMProvider):
+
+ def __init__(self, api_key: str = "no-key", api_base: str = "http://localhost:8000/v1", default_model: str = "default"):
+ super().__init__(api_key, api_base)
+ self.default_model = default_model
+ # Keep affinity stable for this provider instance to improve backend cache locality.
+ self._client = AsyncOpenAI(
+ api_key=api_key,
+ base_url=api_base,
+ default_headers={"x-session-affinity": uuid.uuid4().hex},
+ )
+
+ async def chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None,
+ model: str | None = None, max_tokens: int = 4096, temperature: float = 0.7,
+ reasoning_effort: str | None = None) -> LLMResponse:
+ kwargs: dict[str, Any] = {
+ "model": model or self.default_model,
+ "messages": self._sanitize_empty_content(messages),
+ "max_tokens": max(1, max_tokens),
+ "temperature": temperature,
+ }
+ if reasoning_effort:
+ kwargs["reasoning_effort"] = reasoning_effort
+ if tools:
+ kwargs.update(tools=tools, tool_choice="auto")
+ try:
+ return self._parse(await self._client.chat.completions.create(**kwargs))
+ except Exception as e:
+ return LLMResponse(content=f"Error: {e}", finish_reason="error")
+
+ def _parse(self, response: Any) -> LLMResponse:
+ choice = response.choices[0]
+ msg = choice.message
+ tool_calls = [
+ ToolCallRequest(id=tc.id, name=tc.function.name,
+ arguments=json_repair.loads(tc.function.arguments) if isinstance(tc.function.arguments, str) else tc.function.arguments)
+ for tc in (msg.tool_calls or [])
+ ]
+ u = response.usage
+ return LLMResponse(
+ content=msg.content, tool_calls=tool_calls, finish_reason=choice.finish_reason or "stop",
+ usage={"prompt_tokens": u.prompt_tokens, "completion_tokens": u.completion_tokens, "total_tokens": u.total_tokens} if u else {},
+ reasoning_content=getattr(msg, "reasoning_content", None) or None,
+ )
+
+ def get_default_model(self) -> str:
+ return self.default_model
+
diff --git a/nanobot/nanobot/providers/litellm_provider.py b/nanobot/nanobot/providers/litellm_provider.py
new file mode 100644
index 0000000..cb67635
--- /dev/null
+++ b/nanobot/nanobot/providers/litellm_provider.py
@@ -0,0 +1,340 @@
+"""LiteLLM provider implementation for multi-provider support."""
+
+import hashlib
+import os
+import secrets
+import string
+from typing import Any
+
+import json_repair
+import litellm
+from litellm import acompletion
+from loguru import logger
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from nanobot.providers.registry import find_by_model, find_gateway
+
+# Standard chat-completion message keys.
+_ALLOWED_MSG_KEYS = frozenset({"role", "content", "tool_calls", "tool_call_id", "name", "reasoning_content"})
+_ANTHROPIC_EXTRA_KEYS = frozenset({"thinking_blocks"})
+_ALNUM = string.ascii_letters + string.digits
+
+def _short_tool_id() -> str:
+ """Generate a 9-char alphanumeric ID compatible with all providers (incl. Mistral)."""
+ return "".join(secrets.choice(_ALNUM) for _ in range(9))
+
+
+class LiteLLMProvider(LLMProvider):
+ """
+ LLM provider using LiteLLM for multi-provider support.
+
+ Supports OpenRouter, Anthropic, OpenAI, Gemini, MiniMax, and many other providers through
+ a unified interface. Provider-specific logic is driven by the registry
+ (see providers/registry.py) — no if-elif chains needed here.
+ """
+
+ def __init__(
+ self,
+ api_key: str | None = None,
+ api_base: str | None = None,
+ default_model: str = "anthropic/claude-opus-4-5",
+ extra_headers: dict[str, str] | None = None,
+ provider_name: str | None = None,
+ ):
+ super().__init__(api_key, api_base)
+ self.default_model = default_model
+ self.extra_headers = extra_headers or {}
+
+ # Detect gateway / local deployment.
+ # provider_name (from config key) is the primary signal;
+ # api_key / api_base are fallback for auto-detection.
+ self._gateway = find_gateway(provider_name, api_key, api_base)
+
+ # Configure environment variables
+ if api_key:
+ self._setup_env(api_key, api_base, default_model)
+
+ if api_base:
+ litellm.api_base = api_base
+
+ # Disable LiteLLM logging noise
+ litellm.suppress_debug_info = True
+ # Drop unsupported parameters for providers (e.g., gpt-5 rejects some params)
+ litellm.drop_params = True
+
+ def _setup_env(self, api_key: str, api_base: str | None, model: str) -> None:
+ """Set environment variables based on detected provider."""
+ spec = self._gateway or find_by_model(model)
+ if not spec:
+ return
+ if not spec.env_key:
+ # OAuth/provider-only specs (for example: openai_codex)
+ return
+
+ # Gateway/local overrides existing env; standard provider doesn't
+ if self._gateway:
+ os.environ[spec.env_key] = api_key
+ else:
+ os.environ.setdefault(spec.env_key, api_key)
+
+ # Resolve env_extras placeholders:
+ # {api_key} → user's API key
+ # {api_base} → user's api_base, falling back to spec.default_api_base
+ effective_base = api_base or spec.default_api_base
+ for env_name, env_val in spec.env_extras:
+ resolved = env_val.replace("{api_key}", api_key)
+ resolved = resolved.replace("{api_base}", effective_base)
+ os.environ.setdefault(env_name, resolved)
+
+ def _resolve_model(self, model: str) -> str:
+ """Resolve model name by applying provider/gateway prefixes."""
+ if self._gateway:
+ # Gateway mode: apply gateway prefix, skip provider-specific prefixes
+ prefix = self._gateway.litellm_prefix
+ if self._gateway.strip_model_prefix:
+ model = model.split("/")[-1]
+ if prefix and not model.startswith(f"{prefix}/"):
+ model = f"{prefix}/{model}"
+ return model
+
+ # Standard mode: auto-prefix for known providers
+ spec = find_by_model(model)
+ if spec and spec.litellm_prefix:
+ model = self._canonicalize_explicit_prefix(model, spec.name, spec.litellm_prefix)
+ if not any(model.startswith(s) for s in spec.skip_prefixes):
+ model = f"{spec.litellm_prefix}/{model}"
+
+ return model
+
+ @staticmethod
+ def _canonicalize_explicit_prefix(model: str, spec_name: str, canonical_prefix: str) -> str:
+ """Normalize explicit provider prefixes like `github-copilot/...`."""
+ if "/" not in model:
+ return model
+ prefix, remainder = model.split("/", 1)
+ if prefix.lower().replace("-", "_") != spec_name:
+ return model
+ return f"{canonical_prefix}/{remainder}"
+
+ def _supports_cache_control(self, model: str) -> bool:
+ """Return True when the provider supports cache_control on content blocks."""
+ if self._gateway is not None:
+ return self._gateway.supports_prompt_caching
+ spec = find_by_model(model)
+ return spec is not None and spec.supports_prompt_caching
+
+ def _apply_cache_control(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None,
+ ) -> tuple[list[dict[str, Any]], list[dict[str, Any]] | None]:
+ """Return copies of messages and tools with cache_control injected."""
+ new_messages = []
+ for msg in messages:
+ if msg.get("role") == "system":
+ content = msg["content"]
+ if isinstance(content, str):
+ new_content = [{"type": "text", "text": content, "cache_control": {"type": "ephemeral"}}]
+ else:
+ new_content = list(content)
+ new_content[-1] = {**new_content[-1], "cache_control": {"type": "ephemeral"}}
+ new_messages.append({**msg, "content": new_content})
+ else:
+ new_messages.append(msg)
+
+ new_tools = tools
+ if tools:
+ new_tools = list(tools)
+ new_tools[-1] = {**new_tools[-1], "cache_control": {"type": "ephemeral"}}
+
+ return new_messages, new_tools
+
+ def _apply_model_overrides(self, model: str, kwargs: dict[str, Any]) -> None:
+ """Apply model-specific parameter overrides from the registry."""
+ model_lower = model.lower()
+ spec = find_by_model(model)
+ if spec:
+ for pattern, overrides in spec.model_overrides:
+ if pattern in model_lower:
+ kwargs.update(overrides)
+ return
+
+ @staticmethod
+ def _extra_msg_keys(original_model: str, resolved_model: str) -> frozenset[str]:
+ """Return provider-specific extra keys to preserve in request messages."""
+ spec = find_by_model(original_model) or find_by_model(resolved_model)
+ if (spec and spec.name == "anthropic") or "claude" in original_model.lower() or resolved_model.startswith("anthropic/"):
+ return _ANTHROPIC_EXTRA_KEYS
+ return frozenset()
+
+ @staticmethod
+ def _normalize_tool_call_id(tool_call_id: Any) -> Any:
+ """Normalize tool_call_id to a provider-safe 9-char alphanumeric form."""
+ if not isinstance(tool_call_id, str):
+ return tool_call_id
+ if len(tool_call_id) == 9 and tool_call_id.isalnum():
+ return tool_call_id
+ return hashlib.sha1(tool_call_id.encode()).hexdigest()[:9]
+
+ @staticmethod
+ def _sanitize_messages(messages: list[dict[str, Any]], extra_keys: frozenset[str] = frozenset()) -> list[dict[str, Any]]:
+ """Strip non-standard keys and ensure assistant messages have a content key."""
+ allowed = _ALLOWED_MSG_KEYS | extra_keys
+ sanitized = LLMProvider._sanitize_request_messages(messages, allowed)
+ id_map: dict[str, str] = {}
+
+ def map_id(value: Any) -> Any:
+ if not isinstance(value, str):
+ return value
+ return id_map.setdefault(value, LiteLLMProvider._normalize_tool_call_id(value))
+
+ for clean in sanitized:
+ # Keep assistant tool_calls[].id and tool tool_call_id in sync after
+ # shortening, otherwise strict providers reject the broken linkage.
+ if isinstance(clean.get("tool_calls"), list):
+ normalized_tool_calls = []
+ for tc in clean["tool_calls"]:
+ if not isinstance(tc, dict):
+ normalized_tool_calls.append(tc)
+ continue
+ tc_clean = dict(tc)
+ tc_clean["id"] = map_id(tc_clean.get("id"))
+ normalized_tool_calls.append(tc_clean)
+ clean["tool_calls"] = normalized_tool_calls
+
+ if "tool_call_id" in clean and clean["tool_call_id"]:
+ clean["tool_call_id"] = map_id(clean["tool_call_id"])
+ return sanitized
+
+ async def chat(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None = None,
+ model: str | None = None,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+ reasoning_effort: str | None = None,
+ ) -> LLMResponse:
+ """
+ Send a chat completion request via LiteLLM.
+
+ Args:
+ messages: List of message dicts with 'role' and 'content'.
+ tools: Optional list of tool definitions in OpenAI format.
+ model: Model identifier (e.g., 'anthropic/claude-sonnet-4-5').
+ max_tokens: Maximum tokens in response.
+ temperature: Sampling temperature.
+
+ Returns:
+ LLMResponse with content and/or tool calls.
+ """
+ original_model = model or self.default_model
+ model = self._resolve_model(original_model)
+ extra_msg_keys = self._extra_msg_keys(original_model, model)
+
+ if self._supports_cache_control(original_model):
+ messages, tools = self._apply_cache_control(messages, tools)
+
+ # Clamp max_tokens to at least 1 — negative or zero values cause
+ # LiteLLM to reject the request with "max_tokens must be at least 1".
+ max_tokens = max(1, max_tokens)
+
+ kwargs: dict[str, Any] = {
+ "model": model,
+ "messages": self._sanitize_messages(self._sanitize_empty_content(messages), extra_keys=extra_msg_keys),
+ "max_tokens": max_tokens,
+ "temperature": temperature,
+ }
+
+ # Apply model-specific overrides (e.g. kimi-k2.5 temperature)
+ self._apply_model_overrides(model, kwargs)
+
+ # Pass api_key directly — more reliable than env vars alone
+ if self.api_key:
+ kwargs["api_key"] = self.api_key
+
+ # Pass api_base for custom endpoints
+ if self.api_base:
+ kwargs["api_base"] = self.api_base
+
+ # Pass extra headers (e.g. APP-Code for AiHubMix)
+ if self.extra_headers:
+ kwargs["extra_headers"] = self.extra_headers
+
+ if reasoning_effort:
+ kwargs["reasoning_effort"] = reasoning_effort
+ kwargs["drop_params"] = True
+
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = "auto"
+
+ try:
+ response = await acompletion(**kwargs)
+ return self._parse_response(response)
+ except Exception as e:
+ # Return error as content for graceful handling
+ return LLMResponse(
+ content=f"Error calling LLM: {str(e)}",
+ finish_reason="error",
+ )
+
+ def _parse_response(self, response: Any) -> LLMResponse:
+ """Parse LiteLLM response into our standard format."""
+ choice = response.choices[0]
+ message = choice.message
+ content = message.content
+ finish_reason = choice.finish_reason
+
+ # Some providers (e.g. GitHub Copilot) split content and tool_calls
+ # across multiple choices. Merge them so tool_calls are not lost.
+ raw_tool_calls = []
+ for ch in response.choices:
+ msg = ch.message
+ if hasattr(msg, "tool_calls") and msg.tool_calls:
+ raw_tool_calls.extend(msg.tool_calls)
+ if ch.finish_reason in ("tool_calls", "stop"):
+ finish_reason = ch.finish_reason
+ if not content and msg.content:
+ content = msg.content
+
+ if len(response.choices) > 1:
+ logger.debug("LiteLLM response has {} choices, merged {} tool_calls",
+ len(response.choices), len(raw_tool_calls))
+
+ tool_calls = []
+ for tc in raw_tool_calls:
+ # Parse arguments from JSON string if needed
+ args = tc.function.arguments
+ if isinstance(args, str):
+ args = json_repair.loads(args)
+
+ tool_calls.append(ToolCallRequest(
+ id=_short_tool_id(),
+ name=tc.function.name,
+ arguments=args,
+ ))
+
+ usage = {}
+ if hasattr(response, "usage") and response.usage:
+ usage = {
+ "prompt_tokens": response.usage.prompt_tokens,
+ "completion_tokens": response.usage.completion_tokens,
+ "total_tokens": response.usage.total_tokens,
+ }
+
+ reasoning_content = getattr(message, "reasoning_content", None) or None
+ thinking_blocks = getattr(message, "thinking_blocks", None) or None
+
+ return LLMResponse(
+ content=content,
+ tool_calls=tool_calls,
+ finish_reason=finish_reason or "stop",
+ usage=usage,
+ reasoning_content=reasoning_content,
+ thinking_blocks=thinking_blocks,
+ )
+
+ def get_default_model(self) -> str:
+ """Get the default model."""
+ return self.default_model
diff --git a/nanobot/nanobot/providers/openai_codex_provider.py b/nanobot/nanobot/providers/openai_codex_provider.py
new file mode 100644
index 0000000..d04e210
--- /dev/null
+++ b/nanobot/nanobot/providers/openai_codex_provider.py
@@ -0,0 +1,316 @@
+"""OpenAI Codex Responses Provider."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from typing import Any, AsyncGenerator
+
+import httpx
+from loguru import logger
+from oauth_cli_kit import get_token as get_codex_token
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+DEFAULT_CODEX_URL = "https://chatgpt.com/backend-api/codex/responses"
+DEFAULT_ORIGINATOR = "nanobot"
+
+
+class OpenAICodexProvider(LLMProvider):
+ """Use Codex OAuth to call the Responses API."""
+
+ def __init__(self, default_model: str = "openai-codex/gpt-5.1-codex"):
+ super().__init__(api_key=None, api_base=None)
+ self.default_model = default_model
+
+ async def chat(
+ self,
+ messages: list[dict[str, Any]],
+ tools: list[dict[str, Any]] | None = None,
+ model: str | None = None,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+ reasoning_effort: str | None = None,
+ ) -> LLMResponse:
+ model = model or self.default_model
+ system_prompt, input_items = _convert_messages(messages)
+
+ token = await asyncio.to_thread(get_codex_token)
+ headers = _build_headers(token.account_id, token.access)
+
+ body: dict[str, Any] = {
+ "model": _strip_model_prefix(model),
+ "store": False,
+ "stream": True,
+ "instructions": system_prompt,
+ "input": input_items,
+ "text": {"verbosity": "medium"},
+ "include": ["reasoning.encrypted_content"],
+ "prompt_cache_key": _prompt_cache_key(messages),
+ "tool_choice": "auto",
+ "parallel_tool_calls": True,
+ }
+
+ if reasoning_effort:
+ body["reasoning"] = {"effort": reasoning_effort}
+
+ if tools:
+ body["tools"] = _convert_tools(tools)
+
+ url = DEFAULT_CODEX_URL
+
+ try:
+ try:
+ content, tool_calls, finish_reason = await _request_codex(url, headers, body, verify=True)
+ except Exception as e:
+ if "CERTIFICATE_VERIFY_FAILED" not in str(e):
+ raise
+ logger.warning("SSL certificate verification failed for Codex API; retrying with verify=False")
+ content, tool_calls, finish_reason = await _request_codex(url, headers, body, verify=False)
+ return LLMResponse(
+ content=content,
+ tool_calls=tool_calls,
+ finish_reason=finish_reason,
+ )
+ except Exception as e:
+ return LLMResponse(
+ content=f"Error calling Codex: {str(e)}",
+ finish_reason="error",
+ )
+
+ def get_default_model(self) -> str:
+ return self.default_model
+
+
+def _strip_model_prefix(model: str) -> str:
+ if model.startswith("openai-codex/") or model.startswith("openai_codex/"):
+ return model.split("/", 1)[1]
+ return model
+
+
+def _build_headers(account_id: str, token: str) -> dict[str, str]:
+ return {
+ "Authorization": f"Bearer {token}",
+ "chatgpt-account-id": account_id,
+ "OpenAI-Beta": "responses=experimental",
+ "originator": DEFAULT_ORIGINATOR,
+ "User-Agent": "nanobot (python)",
+ "accept": "text/event-stream",
+ "content-type": "application/json",
+ }
+
+
+async def _request_codex(
+ url: str,
+ headers: dict[str, str],
+ body: dict[str, Any],
+ verify: bool,
+) -> tuple[str, list[ToolCallRequest], str]:
+ async with httpx.AsyncClient(timeout=60.0, verify=verify) as client:
+ async with client.stream("POST", url, headers=headers, json=body) as response:
+ if response.status_code != 200:
+ text = await response.aread()
+ raise RuntimeError(_friendly_error(response.status_code, text.decode("utf-8", "ignore")))
+ return await _consume_sse(response)
+
+
+def _convert_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ """Convert OpenAI function-calling schema to Codex flat format."""
+ converted: list[dict[str, Any]] = []
+ for tool in tools:
+ fn = (tool.get("function") or {}) if tool.get("type") == "function" else tool
+ name = fn.get("name")
+ if not name:
+ continue
+ params = fn.get("parameters") or {}
+ converted.append({
+ "type": "function",
+ "name": name,
+ "description": fn.get("description") or "",
+ "parameters": params if isinstance(params, dict) else {},
+ })
+ return converted
+
+
+def _convert_messages(messages: list[dict[str, Any]]) -> tuple[str, list[dict[str, Any]]]:
+ system_prompt = ""
+ input_items: list[dict[str, Any]] = []
+
+ for idx, msg in enumerate(messages):
+ role = msg.get("role")
+ content = msg.get("content")
+
+ if role == "system":
+ system_prompt = content if isinstance(content, str) else ""
+ continue
+
+ if role == "user":
+ input_items.append(_convert_user_message(content))
+ continue
+
+ if role == "assistant":
+ # Handle text first.
+ if isinstance(content, str) and content:
+ input_items.append(
+ {
+ "type": "message",
+ "role": "assistant",
+ "content": [{"type": "output_text", "text": content}],
+ "status": "completed",
+ "id": f"msg_{idx}",
+ }
+ )
+ # Then handle tool calls.
+ for tool_call in msg.get("tool_calls", []) or []:
+ fn = tool_call.get("function") or {}
+ call_id, item_id = _split_tool_call_id(tool_call.get("id"))
+ call_id = call_id or f"call_{idx}"
+ item_id = item_id or f"fc_{idx}"
+ input_items.append(
+ {
+ "type": "function_call",
+ "id": item_id,
+ "call_id": call_id,
+ "name": fn.get("name"),
+ "arguments": fn.get("arguments") or "{}",
+ }
+ )
+ continue
+
+ if role == "tool":
+ call_id, _ = _split_tool_call_id(msg.get("tool_call_id"))
+ output_text = content if isinstance(content, str) else json.dumps(content, ensure_ascii=False)
+ input_items.append(
+ {
+ "type": "function_call_output",
+ "call_id": call_id,
+ "output": output_text,
+ }
+ )
+ continue
+
+ return system_prompt, input_items
+
+
+def _convert_user_message(content: Any) -> dict[str, Any]:
+ if isinstance(content, str):
+ return {"role": "user", "content": [{"type": "input_text", "text": content}]}
+ if isinstance(content, list):
+ converted: list[dict[str, Any]] = []
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ if item.get("type") == "text":
+ converted.append({"type": "input_text", "text": item.get("text", "")})
+ elif item.get("type") == "image_url":
+ url = (item.get("image_url") or {}).get("url")
+ if url:
+ converted.append({"type": "input_image", "image_url": url, "detail": "auto"})
+ if converted:
+ return {"role": "user", "content": converted}
+ return {"role": "user", "content": [{"type": "input_text", "text": ""}]}
+
+
+def _split_tool_call_id(tool_call_id: Any) -> tuple[str, str | None]:
+ if isinstance(tool_call_id, str) and tool_call_id:
+ if "|" in tool_call_id:
+ call_id, item_id = tool_call_id.split("|", 1)
+ return call_id, item_id or None
+ return tool_call_id, None
+ return "call_0", None
+
+
+def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:
+ raw = json.dumps(messages, ensure_ascii=True, sort_keys=True)
+ return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+async def _iter_sse(response: httpx.Response) -> AsyncGenerator[dict[str, Any], None]:
+ buffer: list[str] = []
+ async for line in response.aiter_lines():
+ if line == "":
+ if buffer:
+ data_lines = [l[5:].strip() for l in buffer if l.startswith("data:")]
+ buffer = []
+ if not data_lines:
+ continue
+ data = "\n".join(data_lines).strip()
+ if not data or data == "[DONE]":
+ continue
+ try:
+ yield json.loads(data)
+ except Exception:
+ continue
+ continue
+ buffer.append(line)
+
+
+async def _consume_sse(response: httpx.Response) -> tuple[str, list[ToolCallRequest], str]:
+ content = ""
+ tool_calls: list[ToolCallRequest] = []
+ tool_call_buffers: dict[str, dict[str, Any]] = {}
+ finish_reason = "stop"
+
+ async for event in _iter_sse(response):
+ event_type = event.get("type")
+ if event_type == "response.output_item.added":
+ item = event.get("item") or {}
+ if item.get("type") == "function_call":
+ call_id = item.get("call_id")
+ if not call_id:
+ continue
+ tool_call_buffers[call_id] = {
+ "id": item.get("id") or "fc_0",
+ "name": item.get("name"),
+ "arguments": item.get("arguments") or "",
+ }
+ elif event_type == "response.output_text.delta":
+ content += event.get("delta") or ""
+ elif event_type == "response.function_call_arguments.delta":
+ call_id = event.get("call_id")
+ if call_id and call_id in tool_call_buffers:
+ tool_call_buffers[call_id]["arguments"] += event.get("delta") or ""
+ elif event_type == "response.function_call_arguments.done":
+ call_id = event.get("call_id")
+ if call_id and call_id in tool_call_buffers:
+ tool_call_buffers[call_id]["arguments"] = event.get("arguments") or ""
+ elif event_type == "response.output_item.done":
+ item = event.get("item") or {}
+ if item.get("type") == "function_call":
+ call_id = item.get("call_id")
+ if not call_id:
+ continue
+ buf = tool_call_buffers.get(call_id) or {}
+ args_raw = buf.get("arguments") or item.get("arguments") or "{}"
+ try:
+ args = json.loads(args_raw)
+ except Exception:
+ args = {"raw": args_raw}
+ tool_calls.append(
+ ToolCallRequest(
+ id=f"{call_id}|{buf.get('id') or item.get('id') or 'fc_0'}",
+ name=buf.get("name") or item.get("name"),
+ arguments=args,
+ )
+ )
+ elif event_type == "response.completed":
+ status = (event.get("response") or {}).get("status")
+ finish_reason = _map_finish_reason(status)
+ elif event_type in {"error", "response.failed"}:
+ raise RuntimeError("Codex response failed")
+
+ return content, tool_calls, finish_reason
+
+
+_FINISH_REASON_MAP = {"completed": "stop", "incomplete": "length", "failed": "error", "cancelled": "error"}
+
+
+def _map_finish_reason(status: str | None) -> str:
+ return _FINISH_REASON_MAP.get(status or "completed", "stop")
+
+
+def _friendly_error(status_code: int, raw: str) -> str:
+ if status_code == 429:
+ return "ChatGPT usage quota exceeded or rate limit triggered. Please try again later."
+ return f"HTTP {status_code}: {raw}"
diff --git a/nanobot/nanobot/providers/registry.py b/nanobot/nanobot/providers/registry.py
new file mode 100644
index 0000000..3ba1a0e
--- /dev/null
+++ b/nanobot/nanobot/providers/registry.py
@@ -0,0 +1,448 @@
+"""
+Provider Registry — single source of truth for LLM provider metadata.
+
+Adding a new provider:
+ 1. Add a ProviderSpec to PROVIDERS below.
+ 2. Add a field to ProvidersConfig in config/schema.py.
+ Done. Env vars, prefixing, config matching, status display all derive from here.
+
+Order matters — it controls match priority and fallback. Gateways first.
+Every entry writes out all fields so you can copy-paste as a template.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+ """One LLM provider's metadata. See PROVIDERS below for real examples.
+
+ Placeholders in env_extras values:
+ {api_key} — the user's API key
+ {api_base} — api_base from config, or this spec's default_api_base
+ """
+
+ # identity
+ name: str # config field name, e.g. "dashscope"
+ keywords: tuple[str, ...] # model-name keywords for matching (lowercase)
+ env_key: str # LiteLLM env var, e.g. "DASHSCOPE_API_KEY"
+ display_name: str = "" # shown in `nanobot status`
+
+ # model prefixing
+ litellm_prefix: str = "" # "dashscope" → model becomes "dashscope/{model}"
+ skip_prefixes: tuple[str, ...] = () # don't prefix if model already starts with these
+
+ # extra env vars, e.g. (("ZHIPUAI_API_KEY", "{api_key}"),)
+ env_extras: tuple[tuple[str, str], ...] = ()
+
+ # gateway / local detection
+ is_gateway: bool = False # routes any model (OpenRouter, AiHubMix)
+ is_local: bool = False # local deployment (vLLM, Ollama)
+ detect_by_key_prefix: str = "" # match api_key prefix, e.g. "sk-or-"
+ detect_by_base_keyword: str = "" # match substring in api_base URL
+ default_api_base: str = "" # fallback base URL
+
+ # gateway behavior
+ strip_model_prefix: bool = False # strip "provider/" before re-prefixing
+
+ # per-model param overrides, e.g. (("kimi-k2.5", {"temperature": 1.0}),)
+ model_overrides: tuple[tuple[str, dict[str, Any]], ...] = ()
+
+ # OAuth-based providers (e.g., OpenAI Codex) don't use API keys
+ is_oauth: bool = False # if True, uses OAuth flow instead of API key
+
+ # Direct providers bypass LiteLLM entirely (e.g., CustomProvider)
+ is_direct: bool = False
+
+ # Provider supports cache_control on content blocks (e.g. Anthropic prompt caching)
+ supports_prompt_caching: bool = False
+
+ @property
+ def label(self) -> str:
+ return self.display_name or self.name.title()
+
+
+# ---------------------------------------------------------------------------
+# PROVIDERS — the registry. Order = priority. Copy any entry as template.
+# ---------------------------------------------------------------------------
+
+PROVIDERS: tuple[ProviderSpec, ...] = (
+ # === Custom (direct OpenAI-compatible endpoint, bypasses LiteLLM) ======
+ ProviderSpec(
+ name="custom",
+ keywords=(),
+ env_key="",
+ display_name="Custom",
+ litellm_prefix="",
+ is_direct=True,
+ ),
+
+ # === Azure OpenAI (direct API calls with API version 2024-10-21) =====
+ ProviderSpec(
+ name="azure_openai",
+ keywords=("azure", "azure-openai"),
+ env_key="",
+ display_name="Azure OpenAI",
+ litellm_prefix="",
+ is_direct=True,
+ ),
+ # === Gateways (detected by api_key / api_base, not model name) =========
+ # Gateways can route any model, so they win in fallback.
+ # OpenRouter: global gateway, keys start with "sk-or-"
+ ProviderSpec(
+ name="openrouter",
+ keywords=("openrouter",),
+ env_key="OPENROUTER_API_KEY",
+ display_name="OpenRouter",
+ litellm_prefix="openrouter", # claude-3 → openrouter/claude-3
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=True,
+ is_local=False,
+ detect_by_key_prefix="sk-or-",
+ detect_by_base_keyword="openrouter",
+ default_api_base="https://openrouter.ai/api/v1",
+ strip_model_prefix=False,
+ model_overrides=(),
+ supports_prompt_caching=True,
+ ),
+ # AiHubMix: global gateway, OpenAI-compatible interface.
+ # strip_model_prefix=True: it doesn't understand "anthropic/claude-3",
+ # so we strip to bare "claude-3" then re-prefix as "openai/claude-3".
+ ProviderSpec(
+ name="aihubmix",
+ keywords=("aihubmix",),
+ env_key="OPENAI_API_KEY", # OpenAI-compatible
+ display_name="AiHubMix",
+ litellm_prefix="openai", # → openai/{model}
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=True,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="aihubmix",
+ default_api_base="https://aihubmix.com/v1",
+ strip_model_prefix=True, # anthropic/claude-3 → claude-3 → openai/claude-3
+ model_overrides=(),
+ ),
+ # SiliconFlow (硅基流动): OpenAI-compatible gateway, model names keep org prefix
+ ProviderSpec(
+ name="siliconflow",
+ keywords=("siliconflow",),
+ env_key="OPENAI_API_KEY",
+ display_name="SiliconFlow",
+ litellm_prefix="openai",
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=True,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="siliconflow",
+ default_api_base="https://api.siliconflow.cn/v1",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # VolcEngine (火山引擎): OpenAI-compatible gateway
+ ProviderSpec(
+ name="volcengine",
+ keywords=("volcengine", "volces", "ark"),
+ env_key="OPENAI_API_KEY",
+ display_name="VolcEngine",
+ litellm_prefix="volcengine",
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=True,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="volces",
+ default_api_base="https://ark.cn-beijing.volces.com/api/v3",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # === Standard providers (matched by model-name keywords) ===============
+ # Anthropic: LiteLLM recognizes "claude-*" natively, no prefix needed.
+ ProviderSpec(
+ name="anthropic",
+ keywords=("anthropic", "claude"),
+ env_key="ANTHROPIC_API_KEY",
+ display_name="Anthropic",
+ litellm_prefix="",
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ supports_prompt_caching=True,
+ ),
+ # OpenAI: LiteLLM recognizes "gpt-*" natively, no prefix needed.
+ ProviderSpec(
+ name="openai",
+ keywords=("openai", "gpt"),
+ env_key="OPENAI_API_KEY",
+ display_name="OpenAI",
+ litellm_prefix="",
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # OpenAI Codex: uses OAuth, not API key.
+ ProviderSpec(
+ name="openai_codex",
+ keywords=("openai-codex",),
+ env_key="", # OAuth-based, no API key
+ display_name="OpenAI Codex",
+ litellm_prefix="", # Not routed through LiteLLM
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="codex",
+ default_api_base="https://chatgpt.com/backend-api",
+ strip_model_prefix=False,
+ model_overrides=(),
+ is_oauth=True, # OAuth-based authentication
+ ),
+ # Github Copilot: uses OAuth, not API key.
+ ProviderSpec(
+ name="github_copilot",
+ keywords=("github_copilot", "copilot"),
+ env_key="", # OAuth-based, no API key
+ display_name="Github Copilot",
+ litellm_prefix="github_copilot", # github_copilot/model → github_copilot/model
+ skip_prefixes=("github_copilot/",),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ is_oauth=True, # OAuth-based authentication
+ ),
+ # DeepSeek: needs "deepseek/" prefix for LiteLLM routing.
+ ProviderSpec(
+ name="deepseek",
+ keywords=("deepseek",),
+ env_key="DEEPSEEK_API_KEY",
+ display_name="DeepSeek",
+ litellm_prefix="deepseek", # deepseek-chat → deepseek/deepseek-chat
+ skip_prefixes=("deepseek/",), # avoid double-prefix
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # Gemini: needs "gemini/" prefix for LiteLLM.
+ ProviderSpec(
+ name="gemini",
+ keywords=("gemini",),
+ env_key="GEMINI_API_KEY",
+ display_name="Gemini",
+ litellm_prefix="gemini", # gemini-pro → gemini/gemini-pro
+ skip_prefixes=("gemini/",), # avoid double-prefix
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # Zhipu: LiteLLM uses "zai/" prefix.
+ # Also mirrors key to ZHIPUAI_API_KEY (some LiteLLM paths check that).
+ # skip_prefixes: don't add "zai/" when already routed via gateway.
+ ProviderSpec(
+ name="zhipu",
+ keywords=("zhipu", "glm", "zai"),
+ env_key="ZAI_API_KEY",
+ display_name="Zhipu AI",
+ litellm_prefix="zai", # glm-4 → zai/glm-4
+ skip_prefixes=("zhipu/", "zai/", "openrouter/", "hosted_vllm/"),
+ env_extras=(("ZHIPUAI_API_KEY", "{api_key}"),),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # DashScope: Qwen models, needs "dashscope/" prefix.
+ ProviderSpec(
+ name="dashscope",
+ keywords=("qwen", "dashscope"),
+ env_key="DASHSCOPE_API_KEY",
+ display_name="DashScope",
+ litellm_prefix="dashscope", # qwen-max → dashscope/qwen-max
+ skip_prefixes=("dashscope/", "openrouter/"),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # Moonshot: Kimi models, needs "moonshot/" prefix.
+ # LiteLLM requires MOONSHOT_API_BASE env var to find the endpoint.
+ # Kimi K2.5 API enforces temperature >= 1.0.
+ ProviderSpec(
+ name="moonshot",
+ keywords=("moonshot", "kimi"),
+ env_key="MOONSHOT_API_KEY",
+ display_name="Moonshot",
+ litellm_prefix="moonshot", # kimi-k2.5 → moonshot/kimi-k2.5
+ skip_prefixes=("moonshot/", "openrouter/"),
+ env_extras=(("MOONSHOT_API_BASE", "{api_base}"),),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="https://api.moonshot.ai/v1", # intl; use api.moonshot.cn for China
+ strip_model_prefix=False,
+ model_overrides=(("kimi-k2.5", {"temperature": 1.0}),),
+ ),
+ # MiniMax: needs "minimax/" prefix for LiteLLM routing.
+ # Uses OpenAI-compatible API at api.minimax.io/v1.
+ ProviderSpec(
+ name="minimax",
+ keywords=("minimax",),
+ env_key="MINIMAX_API_KEY",
+ display_name="MiniMax",
+ litellm_prefix="minimax", # MiniMax-M2.1 → minimax/MiniMax-M2.1
+ skip_prefixes=("minimax/", "openrouter/"),
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="https://api.minimax.io/v1",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # === Local deployment (matched by config key, NOT by api_base) =========
+ # vLLM / any OpenAI-compatible local server.
+ # Detected when config key is "vllm" (provider_name="vllm").
+ ProviderSpec(
+ name="vllm",
+ keywords=("vllm",),
+ env_key="HOSTED_VLLM_API_KEY",
+ display_name="vLLM/Local",
+ litellm_prefix="hosted_vllm", # Llama-3-8B → hosted_vllm/Llama-3-8B
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=False,
+ is_local=True,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="", # user must provide in config
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+ # === Auxiliary (not a primary LLM provider) ============================
+ # Groq: mainly used for Whisper voice transcription, also usable for LLM.
+ # Needs "groq/" prefix for LiteLLM routing. Placed last — it rarely wins fallback.
+ ProviderSpec(
+ name="groq",
+ keywords=("groq",),
+ env_key="GROQ_API_KEY",
+ display_name="Groq",
+ litellm_prefix="groq", # llama3-8b-8192 → groq/llama3-8b-8192
+ skip_prefixes=("groq/",), # avoid double-prefix
+ env_extras=(),
+ is_gateway=False,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="",
+ default_api_base="",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Lookup helpers
+# ---------------------------------------------------------------------------
+
+
+def find_by_model(model: str) -> ProviderSpec | None:
+ """Match a standard provider by model-name keyword (case-insensitive).
+ Skips gateways/local — those are matched by api_key/api_base instead."""
+ model_lower = model.lower()
+ model_normalized = model_lower.replace("-", "_")
+ model_prefix = model_lower.split("/", 1)[0] if "/" in model_lower else ""
+ normalized_prefix = model_prefix.replace("-", "_")
+ std_specs = [s for s in PROVIDERS if not s.is_gateway and not s.is_local]
+
+ # Prefer explicit provider prefix — prevents `github-copilot/...codex` matching openai_codex.
+ for spec in std_specs:
+ if model_prefix and normalized_prefix == spec.name:
+ return spec
+
+ for spec in std_specs:
+ if any(
+ kw in model_lower or kw.replace("-", "_") in model_normalized for kw in spec.keywords
+ ):
+ return spec
+ return None
+
+
+def find_gateway(
+ provider_name: str | None = None,
+ api_key: str | None = None,
+ api_base: str | None = None,
+) -> ProviderSpec | None:
+ """Detect gateway/local provider.
+
+ Priority:
+ 1. provider_name — if it maps to a gateway/local spec, use it directly.
+ 2. api_key prefix — e.g. "sk-or-" → OpenRouter.
+ 3. api_base keyword — e.g. "aihubmix" in URL → AiHubMix.
+
+ A standard provider with a custom api_base (e.g. DeepSeek behind a proxy)
+ will NOT be mistaken for vLLM — the old fallback is gone.
+ """
+ # 1. Direct match by config key
+ if provider_name:
+ spec = find_by_name(provider_name)
+ if spec and (spec.is_gateway or spec.is_local):
+ return spec
+
+ # 2. Auto-detect by api_key prefix / api_base keyword
+ for spec in PROVIDERS:
+ if spec.detect_by_key_prefix and api_key and api_key.startswith(spec.detect_by_key_prefix):
+ return spec
+ if spec.detect_by_base_keyword and api_base and spec.detect_by_base_keyword in api_base:
+ return spec
+
+ return None
+
+
+def find_by_name(name: str) -> ProviderSpec | None:
+ """Find a provider spec by config field name, e.g. "dashscope"."""
+ for spec in PROVIDERS:
+ if spec.name == name:
+ return spec
+ return None
diff --git a/nanobot/nanobot/providers/transcription.py b/nanobot/nanobot/providers/transcription.py
new file mode 100644
index 0000000..1c8cb6a
--- /dev/null
+++ b/nanobot/nanobot/providers/transcription.py
@@ -0,0 +1,64 @@
+"""Voice transcription provider using Groq."""
+
+import os
+from pathlib import Path
+
+import httpx
+from loguru import logger
+
+
+class GroqTranscriptionProvider:
+ """
+ Voice transcription provider using Groq's Whisper API.
+
+ Groq offers extremely fast transcription with a generous free tier.
+ """
+
+ def __init__(self, api_key: str | None = None):
+ self.api_key = api_key or os.environ.get("GROQ_API_KEY")
+ self.api_url = "https://api.groq.com/openai/v1/audio/transcriptions"
+
+ async def transcribe(self, file_path: str | Path) -> str:
+ """
+ Transcribe an audio file using Groq.
+
+ Args:
+ file_path: Path to the audio file.
+
+ Returns:
+ Transcribed text.
+ """
+ if not self.api_key:
+ logger.warning("Groq API key not configured for transcription")
+ return ""
+
+ path = Path(file_path)
+ if not path.exists():
+ logger.error("Audio file not found: {}", file_path)
+ return ""
+
+ try:
+ async with httpx.AsyncClient() as client:
+ with open(path, "rb") as f:
+ files = {
+ "file": (path.name, f),
+ "model": (None, "whisper-large-v3"),
+ }
+ headers = {
+ "Authorization": f"Bearer {self.api_key}",
+ }
+
+ response = await client.post(
+ self.api_url,
+ headers=headers,
+ files=files,
+ timeout=60.0
+ )
+
+ response.raise_for_status()
+ data = response.json()
+ return data.get("text", "")
+
+ except Exception as e:
+ logger.error("Groq transcription error: {}", e)
+ return ""
diff --git a/nanobot/nanobot/session/__init__.py b/nanobot/nanobot/session/__init__.py
new file mode 100644
index 0000000..931f7c6
--- /dev/null
+++ b/nanobot/nanobot/session/__init__.py
@@ -0,0 +1,5 @@
+"""Session management module."""
+
+from nanobot.session.manager import Session, SessionManager
+
+__all__ = ["SessionManager", "Session"]
diff --git a/nanobot/nanobot/session/manager.py b/nanobot/nanobot/session/manager.py
new file mode 100644
index 0000000..f0a6484
--- /dev/null
+++ b/nanobot/nanobot/session/manager.py
@@ -0,0 +1,213 @@
+"""Session management for conversation history."""
+
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from nanobot.config.paths import get_legacy_sessions_dir
+from nanobot.utils.helpers import ensure_dir, safe_filename
+
+
+@dataclass
+class Session:
+ """
+ A conversation session.
+
+ Stores messages in JSONL format for easy reading and persistence.
+
+ Important: Messages are append-only for LLM cache efficiency.
+ The consolidation process writes summaries to MEMORY.md/HISTORY.md
+ but does NOT modify the messages list or get_history() output.
+ """
+
+ key: str # channel:chat_id
+ messages: list[dict[str, Any]] = field(default_factory=list)
+ created_at: datetime = field(default_factory=datetime.now)
+ updated_at: datetime = field(default_factory=datetime.now)
+ metadata: dict[str, Any] = field(default_factory=dict)
+ last_consolidated: int = 0 # Number of messages already consolidated to files
+
+ def add_message(self, role: str, content: str, **kwargs: Any) -> None:
+ """Add a message to the session."""
+ msg = {
+ "role": role,
+ "content": content,
+ "timestamp": datetime.now().isoformat(),
+ **kwargs
+ }
+ self.messages.append(msg)
+ self.updated_at = datetime.now()
+
+ def get_history(self, max_messages: int = 500) -> list[dict[str, Any]]:
+ """Return unconsolidated messages for LLM input, aligned to a user turn."""
+ unconsolidated = self.messages[self.last_consolidated:]
+ sliced = unconsolidated[-max_messages:]
+
+ # Drop leading non-user messages to avoid orphaned tool_result blocks
+ for i, m in enumerate(sliced):
+ if m.get("role") == "user":
+ sliced = sliced[i:]
+ break
+
+ out: list[dict[str, Any]] = []
+ for m in sliced:
+ entry: dict[str, Any] = {"role": m["role"], "content": m.get("content", "")}
+ for k in ("tool_calls", "tool_call_id", "name"):
+ if k in m:
+ entry[k] = m[k]
+ out.append(entry)
+ return out
+
+ def clear(self) -> None:
+ """Clear all messages and reset session to initial state."""
+ self.messages = []
+ self.last_consolidated = 0
+ self.updated_at = datetime.now()
+
+
+class SessionManager:
+ """
+ Manages conversation sessions.
+
+ Sessions are stored as JSONL files in the sessions directory.
+ """
+
+ def __init__(self, workspace: Path):
+ self.workspace = workspace
+ self.sessions_dir = ensure_dir(self.workspace / "sessions")
+ self.legacy_sessions_dir = get_legacy_sessions_dir()
+ self._cache: dict[str, Session] = {}
+
+ def _get_session_path(self, key: str) -> Path:
+ """Get the file path for a session."""
+ safe_key = safe_filename(key.replace(":", "_"))
+ return self.sessions_dir / f"{safe_key}.jsonl"
+
+ def _get_legacy_session_path(self, key: str) -> Path:
+ """Legacy global session path (~/.nanobot/sessions/)."""
+ safe_key = safe_filename(key.replace(":", "_"))
+ return self.legacy_sessions_dir / f"{safe_key}.jsonl"
+
+ def get_or_create(self, key: str) -> Session:
+ """
+ Get an existing session or create a new one.
+
+ Args:
+ key: Session key (usually channel:chat_id).
+
+ Returns:
+ The session.
+ """
+ if key in self._cache:
+ return self._cache[key]
+
+ session = self._load(key)
+ if session is None:
+ session = Session(key=key)
+
+ self._cache[key] = session
+ return session
+
+ def _load(self, key: str) -> Session | None:
+ """Load a session from disk."""
+ path = self._get_session_path(key)
+ if not path.exists():
+ legacy_path = self._get_legacy_session_path(key)
+ if legacy_path.exists():
+ try:
+ shutil.move(str(legacy_path), str(path))
+ logger.info("Migrated session {} from legacy path", key)
+ except Exception:
+ logger.exception("Failed to migrate session {}", key)
+
+ if not path.exists():
+ return None
+
+ try:
+ messages = []
+ metadata = {}
+ created_at = None
+ last_consolidated = 0
+
+ with open(path, encoding="utf-8") as f:
+ for line in f:
+ line = line.strip()
+ if not line:
+ continue
+
+ data = json.loads(line)
+
+ if data.get("_type") == "metadata":
+ metadata = data.get("metadata", {})
+ created_at = datetime.fromisoformat(data["created_at"]) if data.get("created_at") else None
+ last_consolidated = data.get("last_consolidated", 0)
+ else:
+ messages.append(data)
+
+ return Session(
+ key=key,
+ messages=messages,
+ created_at=created_at or datetime.now(),
+ metadata=metadata,
+ last_consolidated=last_consolidated
+ )
+ except Exception as e:
+ logger.warning("Failed to load session {}: {}", key, e)
+ return None
+
+ def save(self, session: Session) -> None:
+ """Save a session to disk."""
+ path = self._get_session_path(session.key)
+
+ with open(path, "w", encoding="utf-8") as f:
+ metadata_line = {
+ "_type": "metadata",
+ "key": session.key,
+ "created_at": session.created_at.isoformat(),
+ "updated_at": session.updated_at.isoformat(),
+ "metadata": session.metadata,
+ "last_consolidated": session.last_consolidated
+ }
+ f.write(json.dumps(metadata_line, ensure_ascii=False) + "\n")
+ for msg in session.messages:
+ f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+
+ self._cache[session.key] = session
+
+ def invalidate(self, key: str) -> None:
+ """Remove a session from the in-memory cache."""
+ self._cache.pop(key, None)
+
+ def list_sessions(self) -> list[dict[str, Any]]:
+ """
+ List all sessions.
+
+ Returns:
+ List of session info dicts.
+ """
+ sessions = []
+
+ for path in self.sessions_dir.glob("*.jsonl"):
+ try:
+ # Read just the metadata line
+ with open(path, encoding="utf-8") as f:
+ first_line = f.readline().strip()
+ if first_line:
+ data = json.loads(first_line)
+ if data.get("_type") == "metadata":
+ key = data.get("key") or path.stem.replace("_", ":", 1)
+ sessions.append({
+ "key": key,
+ "created_at": data.get("created_at"),
+ "updated_at": data.get("updated_at"),
+ "path": str(path)
+ })
+ except Exception:
+ continue
+
+ return sorted(sessions, key=lambda x: x.get("updated_at", ""), reverse=True)
diff --git a/nanobot/nanobot/skills/README.md b/nanobot/nanobot/skills/README.md
new file mode 100644
index 0000000..5192796
--- /dev/null
+++ b/nanobot/nanobot/skills/README.md
@@ -0,0 +1,25 @@
+# nanobot Skills
+
+This directory contains built-in skills that extend nanobot's capabilities.
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` file with:
+- YAML frontmatter (name, description, metadata)
+- Markdown instructions for the agent
+
+## Attribution
+
+These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s skill system.
+The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `github` | Interact with GitHub using the `gh` CLI |
+| `weather` | Get weather info using wttr.in and Open-Meteo |
+| `summarize` | Summarize URLs, files, and YouTube videos |
+| `tmux` | Remote-control tmux sessions |
+| `clawhub` | Search and install skills from ClawHub registry |
+| `skill-creator` | Create new skills |
\ No newline at end of file
diff --git a/nanobot/nanobot/skills/clawhub/SKILL.md b/nanobot/nanobot/skills/clawhub/SKILL.md
new file mode 100644
index 0000000..7409bf4
--- /dev/null
+++ b/nanobot/nanobot/skills/clawhub/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: clawhub
+description: Search and install agent skills from ClawHub, the public skill registry.
+homepage: https://clawhub.ai
+metadata: {"nanobot":{"emoji":"🦞"}}
+---
+
+# ClawHub
+
+Public skill registry for AI agents. Search by natural language (vector search).
+
+## When to use
+
+Use this skill when the user asks any of:
+- "find a skill for …"
+- "search for skills"
+- "install a skill"
+- "what skills are available?"
+- "update my skills"
+
+## Search
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+## Install
+
+```bash
+npx --yes clawhub@latest install --workdir ~/.nanobot/workspace
+```
+
+Replace `` with the skill name from search results. This places the skill into `~/.nanobot/workspace/skills/`, where nanobot loads workspace skills from. Always include `--workdir`.
+
+## Update
+
+```bash
+npx --yes clawhub@latest update --all --workdir ~/.nanobot/workspace
+```
+
+## List installed
+
+```bash
+npx --yes clawhub@latest list --workdir ~/.nanobot/workspace
+```
+
+## Notes
+
+- Requires Node.js (`npx` comes with it).
+- No API key needed for search and install.
+- Login (`npx --yes clawhub@latest login`) is only required for publishing.
+- `--workdir ~/.nanobot/workspace` is critical — without it, skills install to the current directory instead of the nanobot workspace.
+- After install, remind the user to start a new session to load the skill.
diff --git a/nanobot/nanobot/skills/cron/SKILL.md b/nanobot/nanobot/skills/cron/SKILL.md
new file mode 100644
index 0000000..cc3516e
--- /dev/null
+++ b/nanobot/nanobot/skills/cron/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: cron
+description: Schedule reminders and recurring tasks.
+---
+
+# Cron
+
+Use the `cron` tool to schedule reminders or recurring tasks.
+
+## Three Modes
+
+1. **Reminder** - message is sent directly to user
+2. **Task** - message is a task description, agent executes and sends result
+3. **One-time** - runs once at a specific time, then auto-deletes
+
+## Examples
+
+Fixed reminder:
+```
+cron(action="add", message="Time to take a break!", every_seconds=1200)
+```
+
+Dynamic task (agent executes each time):
+```
+cron(action="add", message="Check HKUDS/nanobot GitHub stars and report", every_seconds=600)
+```
+
+One-time scheduled task (compute ISO datetime from current time):
+```
+cron(action="add", message="Remind me about the meeting", at="")
+```
+
+Timezone-aware cron:
+```
+cron(action="add", message="Morning standup", cron_expr="0 9 * * 1-5", tz="America/Vancouver")
+```
+
+List/remove:
+```
+cron(action="list")
+cron(action="remove", job_id="abc123")
+```
+
+## Time Expressions
+
+| User says | Parameters |
+|-----------|------------|
+| every 20 minutes | every_seconds: 1200 |
+| every hour | every_seconds: 3600 |
+| every day at 8am | cron_expr: "0 8 * * *" |
+| weekdays at 5pm | cron_expr: "0 17 * * 1-5" |
+| 9am Vancouver time daily | cron_expr: "0 9 * * *", tz: "America/Vancouver" |
+| at a specific time | at: ISO datetime string (compute from current time) |
+
+## Timezone
+
+Use `tz` with `cron_expr` to schedule in a specific IANA timezone. Without `tz`, the server's local timezone is used.
diff --git a/nanobot/nanobot/skills/github/SKILL.md b/nanobot/nanobot/skills/github/SKILL.md
new file mode 100644
index 0000000..57d8127
--- /dev/null
+++ b/nanobot/nanobot/skills/github/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"nanobot":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output. You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```
diff --git a/nanobot/nanobot/skills/memory/SKILL.md b/nanobot/nanobot/skills/memory/SKILL.md
new file mode 100644
index 0000000..3f0a8fc
--- /dev/null
+++ b/nanobot/nanobot/skills/memory/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: memory
+description: Two-layer memory system with grep-based recall.
+always: true
+---
+
+# Memory
+
+## Structure
+
+- `memory/MEMORY.md` — Long-term facts (preferences, project context, relationships). Always loaded into your context.
+- `memory/HISTORY.md` — Append-only event log. NOT loaded into context. Search it with grep-style tools or in-memory filters. Each entry starts with [YYYY-MM-DD HH:MM].
+
+## Search Past Events
+
+Choose the search method based on file size:
+
+- Small `memory/HISTORY.md`: use `read_file`, then search in-memory
+- Large or long-lived `memory/HISTORY.md`: use the `exec` tool for targeted search
+
+Examples:
+- **Linux/macOS:** `grep -i "keyword" memory/HISTORY.md`
+- **Windows:** `findstr /i "keyword" memory\HISTORY.md`
+- **Cross-platform Python:** `python -c "from pathlib import Path; text = Path('memory/HISTORY.md').read_text(encoding='utf-8'); print('\n'.join([l for l in text.splitlines() if 'keyword' in l.lower()][-20:]))"`
+
+Prefer targeted command-line search for large history files.
+
+## When to Update MEMORY.md
+
+Write important facts immediately using `edit_file` or `write_file`:
+- User preferences ("I prefer dark mode")
+- Project context ("The API uses OAuth2")
+- Relationships ("Alice is the project lead")
+
+## Auto-consolidation
+
+Old conversations are automatically summarized and appended to HISTORY.md when the session grows large. Long-term facts are extracted to MEMORY.md. You don't need to manage this.
diff --git a/nanobot/nanobot/skills/skill-creator/SKILL.md b/nanobot/nanobot/skills/skill-creator/SKILL.md
new file mode 100644
index 0000000..9b5eb6f
--- /dev/null
+++ b/nanobot/nanobot/skills/skill-creator/SKILL.md
@@ -0,0 +1,371 @@
+---
+name: skill-creator
+description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of the agent as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│ ├── YAML frontmatter metadata (required)
+│ │ ├── name: (required)
+│ │ └── description: (required)
+│ └── Markdown instructions (required)
+└── Bundled Resources (optional)
+ ├── scripts/ - Executable code (Python/Bash/etc.)
+ ├── references/ - Documentation intended to be loaded into context as needed
+ └── assets/ - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by the agent for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform the agent's process and thinking.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables the agent to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+the agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+ ├── finance.md (revenue, billing metrics)
+ ├── sales.md (opportunities, pipeline)
+ ├── product.md (API usage, features)
+ └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, the agent only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+ ├── aws.md (AWS deployment patterns)
+ ├── gcp.md (GCP deployment patterns)
+ └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, the agent only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+the agent reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so the agent can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py --path [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path skills/public
+scripts/init_skill.py my-skill --path skills/public --resources scripts,references
+scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help another the agent instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
+ - Include both what the Skill does and specific triggers/contexts for when to use it.
+ - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the agent.
+ - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+
+ - YAML frontmatter format and required fields
+ - Skill naming conventions and directory structure
+ - Description completeness and quality
+ - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
diff --git a/nanobot/nanobot/skills/summarize/SKILL.md b/nanobot/nanobot/skills/summarize/SKILL.md
new file mode 100644
index 0000000..766ab5d
--- /dev/null
+++ b/nanobot/nanobot/skills/summarize/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: summarize
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
+homepage: https://summarize.sh
+metadata: {"nanobot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/summarize","bins":["summarize"],"label":"Install summarize (brew)"}]}}
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com" --model google/gemini-3-flash-preview
+summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `google/gemini-3-flash-preview` if none is set.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|`
+- `--max-output-tokens `
+- `--extract-only` (URLs only)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback
diff --git a/nanobot/nanobot/skills/tmux/SKILL.md b/nanobot/nanobot/skills/tmux/SKILL.md
new file mode 100644
index 0000000..f2a3144
--- /dev/null
+++ b/nanobot/nanobot/skills/tmux/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: tmux
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+metadata: {"nanobot":{"emoji":"🧵","os":["darwin","linux"],"requires":{"bins":["tmux"]}}}
+---
+
+# tmux Skill
+
+Use tmux only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.
+
+## Quickstart (isolated socket, exec tool)
+
+```bash
+SOCKET_DIR="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nanobot.sock"
+SESSION=nanobot-python
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+After starting a session, always print monitor commands:
+
+```
+To monitor:
+ tmux -S "$SOCKET" attach -t "$SESSION"
+ tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Socket convention
+
+- Use `NANOBOT_TMUX_SOCKET_DIR` environment variable.
+- Default socket path: `"$NANOBOT_TMUX_SOCKET_DIR/nanobot.sock"`.
+
+## Targeting panes and naming
+
+- Target format: `session:window.pane` (defaults to `:0.0`).
+- Keep names short; avoid spaces.
+- Inspect: `tmux -S "$SOCKET" list-sessions`, `tmux -S "$SOCKET" list-panes -a`.
+
+## Finding sessions
+
+- List sessions on your socket: `{baseDir}/scripts/find-sessions.sh -S "$SOCKET"`.
+- Scan all sockets: `{baseDir}/scripts/find-sessions.sh --all` (uses `NANOBOT_TMUX_SOCKET_DIR`).
+
+## Sending input safely
+
+- Prefer literal sends: `tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"`.
+- Control keys: `tmux -S "$SOCKET" send-keys -t target C-c`.
+
+## Watching output
+
+- Capture recent history: `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200`.
+- Wait for prompts: `{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'`.
+- Attaching is OK; detach with `Ctrl+b d`.
+
+## Spawning processes
+
+- For python REPLs, set `PYTHON_BASIC_REPL=1` (non-basic REPL breaks send-keys flows).
+
+## Windows / WSL
+
+- tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
+- This skill is gated to `darwin`/`linux` and requires `tmux` on PATH.
+
+## Orchestrating Coding Agents (Codex, Claude Code)
+
+tmux excels at running multiple coding agents in parallel:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
+
+# Create multiple sessions
+for i in 1 2 3 4 5; do
+ tmux -S "$SOCKET" new-session -d -s "agent-$i"
+done
+
+# Launch agents in different workdirs
+tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
+tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter
+
+# Poll for completion (check if prompt returned)
+for sess in agent-1 agent-2; do
+ if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
+ echo "$sess: DONE"
+ else
+ echo "$sess: Running..."
+ fi
+done
+
+# Get full output from completed session
+tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500
+```
+
+**Tips:**
+- Use separate git worktrees for parallel fixes (no branch conflicts)
+- `pnpm install` first before running codex in fresh clones
+- Check for shell prompt (`❯` or `$`) to detect completion
+- Codex needs `--yolo` or `--full-auto` for non-interactive fixes
+
+## Cleanup
+
+- Kill a session: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.
+- Kill all sessions on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
+- Remove everything on the private socket: `tmux -S "$SOCKET" kill-server`.
+
+## Helper: wait-for-text.sh
+
+`{baseDir}/scripts/wait-for-text.sh` polls a pane for a regex (or fixed string) with a timeout.
+
+```bash
+{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
+```
+
+- `-t`/`--target` pane target (required)
+- `-p`/`--pattern` regex to match (required); add `-F` for fixed string
+- `-T` timeout seconds (integer, default 15)
+- `-i` poll interval seconds (default 0.5)
+- `-l` history lines to search (integer, default 1000)
diff --git a/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh b/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh
new file mode 100755
index 0000000..00552c6
--- /dev/null
+++ b/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+ cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+ -L, --socket tmux socket name (passed to tmux -L)
+ -S, --socket-path tmux socket path (passed to tmux -S)
+ -A, --all scan all sockets under NANOBOT_TMUX_SOCKET_DIR
+ -q, --query case-insensitive substring to filter session names
+ -h, --help show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ -L|--socket) socket_name="${2-}"; shift 2 ;;
+ -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+ -A|--all) scan_all=true; shift ;;
+ -q|--query) query="${2-}"; shift 2 ;;
+ -h|--help) usage; exit 0 ;;
+ *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+ esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+ echo "Cannot combine --all with -L or -S" >&2
+ exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+ echo "Use either -L or -S, not both" >&2
+ exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+ echo "tmux not found in PATH" >&2
+ exit 1
+fi
+
+list_sessions() {
+ local label="$1"; shift
+ local tmux_cmd=(tmux "$@")
+
+ if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+ echo "No tmux server found on $label" >&2
+ return 1
+ fi
+
+ if [[ -n "$query" ]]; then
+ sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+ fi
+
+ if [[ -z "$sessions" ]]; then
+ echo "No sessions found on $label"
+ return 0
+ fi
+
+ echo "Sessions on $label:"
+ printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+ attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+ printf ' - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+ done
+}
+
+if [[ "$scan_all" == true ]]; then
+ if [[ ! -d "$socket_dir" ]]; then
+ echo "Socket directory not found: $socket_dir" >&2
+ exit 1
+ fi
+
+ shopt -s nullglob
+ sockets=("$socket_dir"/*)
+ shopt -u nullglob
+
+ if [[ "${#sockets[@]}" -eq 0 ]]; then
+ echo "No sockets found under $socket_dir" >&2
+ exit 1
+ fi
+
+ exit_code=0
+ for sock in "${sockets[@]}"; do
+ if [[ ! -S "$sock" ]]; then
+ continue
+ fi
+ list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+ done
+ exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+ tmux_cmd+=(-L "$socket_name")
+ socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+ tmux_cmd+=(-S "$socket_path")
+ socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"
diff --git a/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh b/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh
new file mode 100755
index 0000000..56354be
--- /dev/null
+++ b/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+ cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+ -t, --target tmux target (session:window.pane), required
+ -p, --pattern regex pattern to look for, required
+ -F, --fixed treat pattern as a fixed string (grep -F)
+ -T, --timeout seconds to wait (integer, default: 15)
+ -i, --interval poll interval in seconds (default: 0.5)
+ -l, --lines number of history lines to inspect (integer, default: 1000)
+ -h, --help show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ -t|--target) target="${2-}"; shift 2 ;;
+ -p|--pattern) pattern="${2-}"; shift 2 ;;
+ -F|--fixed) grep_flag="-F"; shift ;;
+ -T|--timeout) timeout="${2-}"; shift 2 ;;
+ -i|--interval) interval="${2-}"; shift 2 ;;
+ -l|--lines) lines="${2-}"; shift 2 ;;
+ -h|--help) usage; exit 0 ;;
+ *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+ esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+ echo "target and pattern are required" >&2
+ usage
+ exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+ echo "timeout must be an integer number of seconds" >&2
+ exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+ echo "lines must be an integer" >&2
+ exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+ echo "tmux not found in PATH" >&2
+ exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+ # -J joins wrapped lines, -S uses negative index to read last N lines
+ pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+ if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+ exit 0
+ fi
+
+ now=$(date +%s)
+ if (( now >= deadline )); then
+ echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+ echo "Last ${lines} lines from $target:" >&2
+ printf '%s\n' "$pane_text" >&2
+ exit 1
+ fi
+
+ sleep "$interval"
+done
diff --git a/nanobot/nanobot/skills/weather/SKILL.md b/nanobot/nanobot/skills/weather/SKILL.md
new file mode 100644
index 0000000..8073de1
--- /dev/null
+++ b/nanobot/nanobot/skills/weather/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: weather
+description: Get current weather and forecasts (no API key required).
+homepage: https://wttr.in/:help
+metadata: {"nanobot":{"emoji":"🌤️","requires":{"bins":["curl"]}}}
+---
+
+# Weather
+
+Two free services, no API keys needed.
+
+## wttr.in (primary)
+
+Quick one-liner:
+```bash
+curl -s "wttr.in/London?format=3"
+# Output: London: ⛅️ +8°C
+```
+
+Compact format:
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
+# Output: London: ⛅️ +8°C 71% ↙5km/h
+```
+
+Full forecast:
+```bash
+curl -s "wttr.in/London?T"
+```
+
+Format codes: `%c` condition · `%t` temp · `%h` humidity · `%w` wind · `%l` location · `%m` moon
+
+Tips:
+- URL-encode spaces: `wttr.in/New+York`
+- Airport codes: `wttr.in/JFK`
+- Units: `?m` (metric) `?u` (USCS)
+- Today only: `?1` · Current only: `?0`
+- PNG: `curl -s "wttr.in/Berlin.png" -o /tmp/weather.png`
+
+## Open-Meteo (fallback, JSON)
+
+Free, no key, good for programmatic use:
+```bash
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12¤t_weather=true"
+```
+
+Find coordinates for a city, then query. Returns JSON with temp, windspeed, weathercode.
+
+Docs: https://open-meteo.com/en/docs
diff --git a/nanobot/nanobot/templates/AGENTS.md b/nanobot/nanobot/templates/AGENTS.md
new file mode 100644
index 0000000..a24604b
--- /dev/null
+++ b/nanobot/nanobot/templates/AGENTS.md
@@ -0,0 +1,21 @@
+# Agent Instructions
+
+You are a helpful AI assistant. Be concise, accurate, and friendly.
+
+## Scheduled Reminders
+
+Before scheduling reminders, check available skills and follow skill guidance first.
+Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`).
+Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`).
+
+**Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.
+
+## Heartbeat Tasks
+
+`HEARTBEAT.md` is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:
+
+- **Add**: `edit_file` to append new tasks
+- **Remove**: `edit_file` to delete completed tasks
+- **Rewrite**: `write_file` to replace all tasks
+
+When the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.
diff --git a/nanobot/nanobot/templates/HEARTBEAT.md b/nanobot/nanobot/templates/HEARTBEAT.md
new file mode 100644
index 0000000..322dbeb
--- /dev/null
+++ b/nanobot/nanobot/templates/HEARTBEAT.md
@@ -0,0 +1,16 @@
+# Heartbeat Tasks
+
+This file is checked every 30 minutes by your nanobot agent.
+Add tasks below that you want the agent to work on periodically.
+
+If this file has no tasks (only headers and comments), the agent will skip the heartbeat.
+
+## Active Tasks
+
+
+
+
+## Completed
+
+
+
diff --git a/nanobot/nanobot/templates/SOUL.md b/nanobot/nanobot/templates/SOUL.md
new file mode 100644
index 0000000..59403e7
--- /dev/null
+++ b/nanobot/nanobot/templates/SOUL.md
@@ -0,0 +1,21 @@
+# Soul
+
+I am nanobot 🐈, a personal AI assistant.
+
+## Personality
+
+- Helpful and friendly
+- Concise and to the point
+- Curious and eager to learn
+
+## Values
+
+- Accuracy over speed
+- User privacy and safety
+- Transparency in actions
+
+## Communication Style
+
+- Be clear and direct
+- Explain reasoning when helpful
+- Ask clarifying questions when needed
diff --git a/nanobot/nanobot/templates/TOOLS.md b/nanobot/nanobot/templates/TOOLS.md
new file mode 100644
index 0000000..51c3a2d
--- /dev/null
+++ b/nanobot/nanobot/templates/TOOLS.md
@@ -0,0 +1,15 @@
+# Tool Usage Notes
+
+Tool signatures are provided automatically via function calling.
+This file documents non-obvious constraints and usage patterns.
+
+## exec — Safety Limits
+
+- Commands have a configurable timeout (default 60s)
+- Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)
+- Output is truncated at 10,000 characters
+- `restrictToWorkspace` config can limit file access to the workspace
+
+## cron — Scheduled Reminders
+
+- Please refer to cron skill for usage.
diff --git a/nanobot/nanobot/templates/USER.md b/nanobot/nanobot/templates/USER.md
new file mode 100644
index 0000000..671ec49
--- /dev/null
+++ b/nanobot/nanobot/templates/USER.md
@@ -0,0 +1,49 @@
+# User Profile
+
+Information about the user to help personalize interactions.
+
+## Basic Information
+
+- **Name**: (your name)
+- **Timezone**: (your timezone, e.g., UTC+8)
+- **Language**: (preferred language)
+
+## Preferences
+
+### Communication Style
+
+- [ ] Casual
+- [ ] Professional
+- [ ] Technical
+
+### Response Length
+
+- [ ] Brief and concise
+- [ ] Detailed explanations
+- [ ] Adaptive based on question
+
+### Technical Level
+
+- [ ] Beginner
+- [ ] Intermediate
+- [ ] Expert
+
+## Work Context
+
+- **Primary Role**: (your role, e.g., developer, researcher)
+- **Main Projects**: (what you're working on)
+- **Tools You Use**: (IDEs, languages, frameworks)
+
+## Topics of Interest
+
+-
+-
+-
+
+## Special Instructions
+
+(Any specific instructions for how the assistant should behave)
+
+---
+
+*Edit this file to customize nanobot's behavior for your needs.*
diff --git a/nanobot/nanobot/templates/__init__.py b/nanobot/nanobot/templates/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/nanobot/nanobot/templates/memory/MEMORY.md b/nanobot/nanobot/templates/memory/MEMORY.md
new file mode 100644
index 0000000..fd2ca96
--- /dev/null
+++ b/nanobot/nanobot/templates/memory/MEMORY.md
@@ -0,0 +1,23 @@
+# Long-term Memory
+
+This file stores important information that should persist across sessions.
+
+## User Information
+
+(Important facts about the user)
+
+## Preferences
+
+(User preferences learned over time)
+
+## Project Context
+
+(Information about ongoing projects)
+
+## Important Notes
+
+(Things to remember)
+
+---
+
+*This file is automatically updated by nanobot when important information should be remembered.*
diff --git a/nanobot/nanobot/templates/memory/__init__.py b/nanobot/nanobot/templates/memory/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/nanobot/nanobot/utils/__init__.py b/nanobot/nanobot/utils/__init__.py
new file mode 100644
index 0000000..46f02ac
--- /dev/null
+++ b/nanobot/nanobot/utils/__init__.py
@@ -0,0 +1,5 @@
+"""Utility functions for nanobot."""
+
+from nanobot.utils.helpers import ensure_dir
+
+__all__ = ["ensure_dir"]
diff --git a/nanobot/nanobot/utils/helpers.py b/nanobot/nanobot/utils/helpers.py
new file mode 100644
index 0000000..57c60dc
--- /dev/null
+++ b/nanobot/nanobot/utils/helpers.py
@@ -0,0 +1,101 @@
+"""Utility functions for nanobot."""
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+def detect_image_mime(data: bytes) -> str | None:
+ """Detect image MIME type from magic bytes, ignoring file extension."""
+ if data[:8] == b"\x89PNG\r\n\x1a\n":
+ return "image/png"
+ if data[:3] == b"\xff\xd8\xff":
+ return "image/jpeg"
+ if data[:6] in (b"GIF87a", b"GIF89a"):
+ return "image/gif"
+ if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+ return "image/webp"
+ return None
+
+
+def ensure_dir(path: Path) -> Path:
+ """Ensure directory exists, return it."""
+ path.mkdir(parents=True, exist_ok=True)
+ return path
+
+
+def timestamp() -> str:
+ """Current ISO timestamp."""
+ return datetime.now().isoformat()
+
+
+_UNSAFE_CHARS = re.compile(r'[<>:"/\\|?*]')
+
+def safe_filename(name: str) -> str:
+ """Replace unsafe path characters with underscores."""
+ return _UNSAFE_CHARS.sub("_", name).strip()
+
+
+def split_message(content: str, max_len: int = 2000) -> list[str]:
+ """
+ Split content into chunks within max_len, preferring line breaks.
+
+ Args:
+ content: The text content to split.
+ max_len: Maximum length per chunk (default 2000 for Discord compatibility).
+
+ Returns:
+ List of message chunks, each within max_len.
+ """
+ if not content:
+ return []
+ if len(content) <= max_len:
+ return [content]
+ chunks: list[str] = []
+ while content:
+ if len(content) <= max_len:
+ chunks.append(content)
+ break
+ cut = content[:max_len]
+ # Try to break at newline first, then space, then hard break
+ pos = cut.rfind('\n')
+ if pos <= 0:
+ pos = cut.rfind(' ')
+ if pos <= 0:
+ pos = max_len
+ chunks.append(content[:pos])
+ content = content[pos:].lstrip()
+ return chunks
+
+
+def sync_workspace_templates(workspace: Path, silent: bool = False) -> list[str]:
+ """Sync bundled templates to workspace. Only creates missing files."""
+ from importlib.resources import files as pkg_files
+ try:
+ tpl = pkg_files("nanobot") / "templates"
+ except Exception:
+ return []
+ if not tpl.is_dir():
+ return []
+
+ added: list[str] = []
+
+ def _write(src, dest: Path):
+ if dest.exists():
+ return
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ dest.write_text(src.read_text(encoding="utf-8") if src else "", encoding="utf-8")
+ added.append(str(dest.relative_to(workspace)))
+
+ for item in tpl.iterdir():
+ if item.name.endswith(".md"):
+ _write(item, workspace / item.name)
+ _write(tpl / "memory" / "MEMORY.md", workspace / "memory" / "MEMORY.md")
+ _write(None, workspace / "memory" / "HISTORY.md")
+ (workspace / "skills").mkdir(exist_ok=True)
+
+ if added and not silent:
+ from rich.console import Console
+ for name in added:
+ Console().print(f" [dim]Created {name}[/dim]")
+ return added
diff --git a/nanobot/nanobot_arch.png b/nanobot/nanobot_arch.png
new file mode 100644
index 0000000..0925177
Binary files /dev/null and b/nanobot/nanobot_arch.png differ
diff --git a/nanobot/nanobot_logo.png b/nanobot/nanobot_logo.png
new file mode 100644
index 0000000..01055d1
Binary files /dev/null and b/nanobot/nanobot_logo.png differ
diff --git a/nanobot/pyproject.toml b/nanobot/pyproject.toml
new file mode 100644
index 0000000..62cf616
--- /dev/null
+++ b/nanobot/pyproject.toml
@@ -0,0 +1,107 @@
+[project]
+name = "nanobot-ai"
+version = "0.1.4.post4"
+description = "A lightweight personal AI assistant framework"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+ {name = "nanobot contributors"}
+]
+keywords = ["ai", "agent", "chatbot"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+ "typer>=0.20.0,<1.0.0",
+ "litellm>=1.81.5,<2.0.0",
+ "pydantic>=2.12.0,<3.0.0",
+ "pydantic-settings>=2.12.0,<3.0.0",
+ "websockets>=16.0,<17.0",
+ "websocket-client>=1.9.0,<2.0.0",
+ "httpx>=0.28.0,<1.0.0",
+ "oauth-cli-kit>=0.1.3,<1.0.0",
+ "loguru>=0.7.3,<1.0.0",
+ "readability-lxml>=0.8.4,<1.0.0",
+ "rich>=14.0.0,<15.0.0",
+ "croniter>=6.0.0,<7.0.0",
+ "dingtalk-stream>=0.24.0,<1.0.0",
+ "python-telegram-bot[socks]>=22.6,<23.0",
+ "lark-oapi>=1.5.0,<2.0.0",
+ "socksio>=1.0.0,<2.0.0",
+ "python-socketio>=5.16.0,<6.0.0",
+ "msgpack>=1.1.0,<2.0.0",
+ "slack-sdk>=3.39.0,<4.0.0",
+ "slackify-markdown>=0.2.0,<1.0.0",
+ "qq-botpy>=1.2.0,<2.0.0",
+ "python-socks[asyncio]>=2.8.0,<3.0.0",
+ "prompt-toolkit>=3.0.50,<4.0.0",
+ "mcp>=1.26.0,<2.0.0",
+ "json-repair>=0.57.0,<1.0.0",
+ "chardet>=3.0.2,<6.0.0",
+ "openai>=2.8.0",
+]
+
+[project.optional-dependencies]
+matrix = [
+ "matrix-nio[e2e]>=0.25.2",
+ "mistune>=3.0.0,<4.0.0",
+ "nh3>=0.2.17,<1.0.0",
+]
+dev = [
+ "pytest>=9.0.0,<10.0.0",
+ "pytest-asyncio>=1.3.0,<2.0.0",
+ "ruff>=0.1.0",
+ "matrix-nio[e2e]>=0.25.2",
+ "mistune>=3.0.0,<4.0.0",
+ "nh3>=0.2.17,<1.0.0",
+]
+
+[project.scripts]
+nanobot = "nanobot.cli.commands:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nanobot"]
+
+[tool.hatch.build.targets.wheel.sources]
+"nanobot" = "nanobot"
+
+# Include non-Python files in skills and templates
+[tool.hatch.build]
+include = [
+ "nanobot/**/*.py",
+ "nanobot/templates/**/*.md",
+ "nanobot/skills/**/*.md",
+ "nanobot/skills/**/*.sh",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+ "nanobot/",
+ "bridge/",
+ "README.md",
+ "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel.force-include]
+"bridge" = "nanobot/bridge"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
diff --git a/nanobot/tests/test_azure_openai_provider.py b/nanobot/tests/test_azure_openai_provider.py
new file mode 100644
index 0000000..77f36d4
--- /dev/null
+++ b/nanobot/tests/test_azure_openai_provider.py
@@ -0,0 +1,399 @@
+"""Test Azure OpenAI provider implementation (updated for model-based deployment names)."""
+
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+from nanobot.providers.base import LLMResponse
+
+
+def test_azure_openai_provider_init():
+ """Test AzureOpenAIProvider initialization without deployment_name."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o-deployment",
+ )
+
+ assert provider.api_key == "test-key"
+ assert provider.api_base == "https://test-resource.openai.azure.com/"
+ assert provider.default_model == "gpt-4o-deployment"
+ assert provider.api_version == "2024-10-21"
+
+
+def test_azure_openai_provider_init_validation():
+ """Test AzureOpenAIProvider initialization validation."""
+ # Missing api_key
+ with pytest.raises(ValueError, match="Azure OpenAI api_key is required"):
+ AzureOpenAIProvider(api_key="", api_base="https://test.com")
+
+ # Missing api_base
+ with pytest.raises(ValueError, match="Azure OpenAI api_base is required"):
+ AzureOpenAIProvider(api_key="test", api_base="")
+
+
+def test_build_chat_url():
+ """Test Azure OpenAI URL building with different deployment names."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ # Test various deployment names
+ test_cases = [
+ ("gpt-4o-deployment", "https://test-resource.openai.azure.com/openai/deployments/gpt-4o-deployment/chat/completions?api-version=2024-10-21"),
+ ("gpt-35-turbo", "https://test-resource.openai.azure.com/openai/deployments/gpt-35-turbo/chat/completions?api-version=2024-10-21"),
+ ("custom-model", "https://test-resource.openai.azure.com/openai/deployments/custom-model/chat/completions?api-version=2024-10-21"),
+ ]
+
+ for deployment_name, expected_url in test_cases:
+ url = provider._build_chat_url(deployment_name)
+ assert url == expected_url
+
+
+def test_build_chat_url_api_base_without_slash():
+ """Test URL building when api_base doesn't end with slash."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com", # No trailing slash
+ default_model="gpt-4o",
+ )
+
+ url = provider._build_chat_url("test-deployment")
+ expected = "https://test-resource.openai.azure.com/openai/deployments/test-deployment/chat/completions?api-version=2024-10-21"
+ assert url == expected
+
+
+def test_build_headers():
+ """Test Azure OpenAI header building with api-key authentication."""
+ provider = AzureOpenAIProvider(
+ api_key="test-api-key-123",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ headers = provider._build_headers()
+ assert headers["Content-Type"] == "application/json"
+ assert headers["api-key"] == "test-api-key-123" # Azure OpenAI specific header
+ assert "x-session-affinity" in headers
+
+
+def test_prepare_request_payload():
+ """Test request payload preparation with Azure OpenAI 2024-10-21 compliance."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ messages = [{"role": "user", "content": "Hello"}]
+ payload = provider._prepare_request_payload("gpt-4o", messages, max_tokens=1500, temperature=0.8)
+
+ assert payload["messages"] == messages
+ assert payload["max_completion_tokens"] == 1500 # Azure API 2024-10-21 uses max_completion_tokens
+ assert payload["temperature"] == 0.8
+ assert "tools" not in payload
+
+ # Test with tools
+ tools = [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}]
+ payload_with_tools = provider._prepare_request_payload("gpt-4o", messages, tools=tools)
+ assert payload_with_tools["tools"] == tools
+ assert payload_with_tools["tool_choice"] == "auto"
+
+ # Test with reasoning_effort
+ payload_with_reasoning = provider._prepare_request_payload(
+ "gpt-5-chat", messages, reasoning_effort="medium"
+ )
+ assert payload_with_reasoning["reasoning_effort"] == "medium"
+ assert "temperature" not in payload_with_reasoning
+
+
+def test_prepare_request_payload_sanitizes_messages():
+ """Test Azure payload strips non-standard message keys before sending."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ messages = [
+ {
+ "role": "assistant",
+ "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "x"}}],
+ "reasoning_content": "hidden chain-of-thought",
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_123",
+ "name": "x",
+ "content": "ok",
+ "extra_field": "should be removed",
+ },
+ ]
+
+ payload = provider._prepare_request_payload("gpt-4o", messages)
+
+ assert payload["messages"] == [
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "x"}}],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_123",
+ "name": "x",
+ "content": "ok",
+ },
+ ]
+
+
+@pytest.mark.asyncio
+async def test_chat_success():
+ """Test successful chat request using model as deployment name."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o-deployment",
+ )
+
+ # Mock response data
+ mock_response_data = {
+ "choices": [{
+ "message": {
+ "content": "Hello! How can I help you today?",
+ "role": "assistant"
+ },
+ "finish_reason": "stop"
+ }],
+ "usage": {
+ "prompt_tokens": 12,
+ "completion_tokens": 18,
+ "total_tokens": 30
+ }
+ }
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_response = AsyncMock()
+ mock_response.status_code = 200
+ mock_response.json = Mock(return_value=mock_response_data)
+
+ mock_context = AsyncMock()
+ mock_context.post = AsyncMock(return_value=mock_response)
+ mock_client.return_value.__aenter__.return_value = mock_context
+
+ # Test with specific model (deployment name)
+ messages = [{"role": "user", "content": "Hello"}]
+ result = await provider.chat(messages, model="custom-deployment")
+
+ assert isinstance(result, LLMResponse)
+ assert result.content == "Hello! How can I help you today?"
+ assert result.finish_reason == "stop"
+ assert result.usage["prompt_tokens"] == 12
+ assert result.usage["completion_tokens"] == 18
+ assert result.usage["total_tokens"] == 30
+
+ # Verify URL was built with the provided model as deployment name
+ call_args = mock_context.post.call_args
+ expected_url = "https://test-resource.openai.azure.com/openai/deployments/custom-deployment/chat/completions?api-version=2024-10-21"
+ assert call_args[0][0] == expected_url
+
+
+@pytest.mark.asyncio
+async def test_chat_uses_default_model_when_no_model_provided():
+ """Test that chat uses default_model when no model is specified."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="default-deployment",
+ )
+
+ mock_response_data = {
+ "choices": [{
+ "message": {"content": "Response", "role": "assistant"},
+ "finish_reason": "stop"
+ }],
+ "usage": {"prompt_tokens": 5, "completion_tokens": 5, "total_tokens": 10}
+ }
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_response = AsyncMock()
+ mock_response.status_code = 200
+ mock_response.json = Mock(return_value=mock_response_data)
+
+ mock_context = AsyncMock()
+ mock_context.post = AsyncMock(return_value=mock_response)
+ mock_client.return_value.__aenter__.return_value = mock_context
+
+ messages = [{"role": "user", "content": "Test"}]
+ await provider.chat(messages) # No model specified
+
+ # Verify URL was built with default model as deployment name
+ call_args = mock_context.post.call_args
+ expected_url = "https://test-resource.openai.azure.com/openai/deployments/default-deployment/chat/completions?api-version=2024-10-21"
+ assert call_args[0][0] == expected_url
+
+
+@pytest.mark.asyncio
+async def test_chat_with_tool_calls():
+ """Test chat request with tool calls in response."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ # Mock response with tool calls
+ mock_response_data = {
+ "choices": [{
+ "message": {
+ "content": None,
+ "role": "assistant",
+ "tool_calls": [{
+ "id": "call_12345",
+ "function": {
+ "name": "get_weather",
+ "arguments": '{"location": "San Francisco"}'
+ }
+ }]
+ },
+ "finish_reason": "tool_calls"
+ }],
+ "usage": {
+ "prompt_tokens": 20,
+ "completion_tokens": 15,
+ "total_tokens": 35
+ }
+ }
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_response = AsyncMock()
+ mock_response.status_code = 200
+ mock_response.json = Mock(return_value=mock_response_data)
+
+ mock_context = AsyncMock()
+ mock_context.post = AsyncMock(return_value=mock_response)
+ mock_client.return_value.__aenter__.return_value = mock_context
+
+ messages = [{"role": "user", "content": "What's the weather?"}]
+ tools = [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}]
+ result = await provider.chat(messages, tools=tools, model="weather-model")
+
+ assert isinstance(result, LLMResponse)
+ assert result.content is None
+ assert result.finish_reason == "tool_calls"
+ assert len(result.tool_calls) == 1
+ assert result.tool_calls[0].name == "get_weather"
+ assert result.tool_calls[0].arguments == {"location": "San Francisco"}
+
+
+@pytest.mark.asyncio
+async def test_chat_api_error():
+ """Test chat request API error handling."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_response = AsyncMock()
+ mock_response.status_code = 401
+ mock_response.text = "Invalid authentication credentials"
+
+ mock_context = AsyncMock()
+ mock_context.post = AsyncMock(return_value=mock_response)
+ mock_client.return_value.__aenter__.return_value = mock_context
+
+ messages = [{"role": "user", "content": "Hello"}]
+ result = await provider.chat(messages)
+
+ assert isinstance(result, LLMResponse)
+ assert "Azure OpenAI API Error 401" in result.content
+ assert "Invalid authentication credentials" in result.content
+ assert result.finish_reason == "error"
+
+
+@pytest.mark.asyncio
+async def test_chat_connection_error():
+ """Test chat request connection error handling."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ with patch("httpx.AsyncClient") as mock_client:
+ mock_context = AsyncMock()
+ mock_context.post = AsyncMock(side_effect=Exception("Connection failed"))
+ mock_client.return_value.__aenter__.return_value = mock_context
+
+ messages = [{"role": "user", "content": "Hello"}]
+ result = await provider.chat(messages)
+
+ assert isinstance(result, LLMResponse)
+ assert "Error calling Azure OpenAI: Exception('Connection failed')" in result.content
+ assert result.finish_reason == "error"
+
+
+def test_parse_response_malformed():
+ """Test response parsing with malformed data."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o",
+ )
+
+ # Test with missing choices
+ malformed_response = {"usage": {"prompt_tokens": 10}}
+ result = provider._parse_response(malformed_response)
+
+ assert isinstance(result, LLMResponse)
+ assert "Error parsing Azure OpenAI response" in result.content
+ assert result.finish_reason == "error"
+
+
+def test_get_default_model():
+ """Test get_default_model method."""
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="my-custom-deployment",
+ )
+
+ assert provider.get_default_model() == "my-custom-deployment"
+
+
+if __name__ == "__main__":
+ # Run basic tests
+ print("Running basic Azure OpenAI provider tests...")
+
+ # Test initialization
+ provider = AzureOpenAIProvider(
+ api_key="test-key",
+ api_base="https://test-resource.openai.azure.com",
+ default_model="gpt-4o-deployment",
+ )
+ print("✅ Provider initialization successful")
+
+ # Test URL building
+ url = provider._build_chat_url("my-deployment")
+ expected = "https://test-resource.openai.azure.com/openai/deployments/my-deployment/chat/completions?api-version=2024-10-21"
+ assert url == expected
+ print("✅ URL building works correctly")
+
+ # Test headers
+ headers = provider._build_headers()
+ assert headers["api-key"] == "test-key"
+ assert headers["Content-Type"] == "application/json"
+ print("✅ Header building works correctly")
+
+ # Test payload preparation
+ messages = [{"role": "user", "content": "Test"}]
+ payload = provider._prepare_request_payload("gpt-4o-deployment", messages, max_tokens=1000)
+ assert payload["max_completion_tokens"] == 1000 # Azure 2024-10-21 format
+ print("✅ Payload preparation works correctly")
+
+ print("✅ All basic tests passed! Updated test file is working correctly.")
\ No newline at end of file
diff --git a/nanobot/tests/test_base_channel.py b/nanobot/tests/test_base_channel.py
new file mode 100644
index 0000000..5d10d4e
--- /dev/null
+++ b/nanobot/tests/test_base_channel.py
@@ -0,0 +1,25 @@
+from types import SimpleNamespace
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+
+
+class _DummyChannel(BaseChannel):
+ name = "dummy"
+
+ async def start(self) -> None:
+ return None
+
+ async def stop(self) -> None:
+ return None
+
+ async def send(self, msg: OutboundMessage) -> None:
+ return None
+
+
+def test_is_allowed_requires_exact_match() -> None:
+ channel = _DummyChannel(SimpleNamespace(allow_from=["allow@email.com"]), MessageBus())
+
+ assert channel.is_allowed("allow@email.com") is True
+ assert channel.is_allowed("attacker|allow@email.com") is False
diff --git a/nanobot/tests/test_cli_input.py b/nanobot/tests/test_cli_input.py
new file mode 100644
index 0000000..9626120
--- /dev/null
+++ b/nanobot/tests/test_cli_input.py
@@ -0,0 +1,59 @@
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from prompt_toolkit.formatted_text import HTML
+
+from nanobot.cli import commands
+
+
+@pytest.fixture
+def mock_prompt_session():
+ """Mock the global prompt session."""
+ mock_session = MagicMock()
+ mock_session.prompt_async = AsyncMock()
+ with patch("nanobot.cli.commands._PROMPT_SESSION", mock_session), \
+ patch("nanobot.cli.commands.patch_stdout"):
+ yield mock_session
+
+
+@pytest.mark.asyncio
+async def test_read_interactive_input_async_returns_input(mock_prompt_session):
+ """Test that _read_interactive_input_async returns the user input from prompt_session."""
+ mock_prompt_session.prompt_async.return_value = "hello world"
+
+ result = await commands._read_interactive_input_async()
+
+ assert result == "hello world"
+ mock_prompt_session.prompt_async.assert_called_once()
+ args, _ = mock_prompt_session.prompt_async.call_args
+ assert isinstance(args[0], HTML) # Verify HTML prompt is used
+
+
+@pytest.mark.asyncio
+async def test_read_interactive_input_async_handles_eof(mock_prompt_session):
+ """Test that EOFError converts to KeyboardInterrupt."""
+ mock_prompt_session.prompt_async.side_effect = EOFError()
+
+ with pytest.raises(KeyboardInterrupt):
+ await commands._read_interactive_input_async()
+
+
+def test_init_prompt_session_creates_session():
+ """Test that _init_prompt_session initializes the global session."""
+ # Ensure global is None before test
+ commands._PROMPT_SESSION = None
+
+ with patch("nanobot.cli.commands.PromptSession") as MockSession, \
+ patch("nanobot.cli.commands.FileHistory") as MockHistory, \
+ patch("pathlib.Path.home") as mock_home:
+
+ mock_home.return_value = MagicMock()
+
+ commands._init_prompt_session()
+
+ assert commands._PROMPT_SESSION is not None
+ MockSession.assert_called_once()
+ _, kwargs = MockSession.call_args
+ assert kwargs["multiline"] is False
+ assert kwargs["enable_open_in_editor"] is False
diff --git a/nanobot/tests/test_commands.py b/nanobot/tests/test_commands.py
new file mode 100644
index 0000000..19c1998
--- /dev/null
+++ b/nanobot/tests/test_commands.py
@@ -0,0 +1,358 @@
+import shutil
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from nanobot.cli.commands import app
+from nanobot.config.schema import Config
+from nanobot.providers.litellm_provider import LiteLLMProvider
+from nanobot.providers.openai_codex_provider import _strip_model_prefix
+from nanobot.providers.registry import find_by_model
+
+runner = CliRunner()
+
+
+class _StopGateway(RuntimeError):
+ pass
+
+
+@pytest.fixture
+def mock_paths():
+ """Mock config/workspace paths for test isolation."""
+ with patch("nanobot.config.loader.get_config_path") as mock_cp, \
+ patch("nanobot.config.loader.save_config") as mock_sc, \
+ patch("nanobot.config.loader.load_config") as mock_lc, \
+ patch("nanobot.cli.commands.get_workspace_path") as mock_ws:
+
+ base_dir = Path("./test_onboard_data")
+ if base_dir.exists():
+ shutil.rmtree(base_dir)
+ base_dir.mkdir()
+
+ config_file = base_dir / "config.json"
+ workspace_dir = base_dir / "workspace"
+
+ mock_cp.return_value = config_file
+ mock_ws.return_value = workspace_dir
+ mock_sc.side_effect = lambda config: config_file.write_text("{}")
+
+ yield config_file, workspace_dir
+
+ if base_dir.exists():
+ shutil.rmtree(base_dir)
+
+
+def test_onboard_fresh_install(mock_paths):
+ """No existing config — should create from scratch."""
+ config_file, workspace_dir = mock_paths
+
+ result = runner.invoke(app, ["onboard"])
+
+ assert result.exit_code == 0
+ assert "Created config" in result.stdout
+ assert "Created workspace" in result.stdout
+ assert "nanobot is ready" in result.stdout
+ assert config_file.exists()
+ assert (workspace_dir / "AGENTS.md").exists()
+ assert (workspace_dir / "memory" / "MEMORY.md").exists()
+
+
+def test_onboard_existing_config_refresh(mock_paths):
+ """Config exists, user declines overwrite — should refresh (load-merge-save)."""
+ config_file, workspace_dir = mock_paths
+ config_file.write_text('{"existing": true}')
+
+ result = runner.invoke(app, ["onboard"], input="n\n")
+
+ assert result.exit_code == 0
+ assert "Config already exists" in result.stdout
+ assert "existing values preserved" in result.stdout
+ assert workspace_dir.exists()
+ assert (workspace_dir / "AGENTS.md").exists()
+
+
+def test_onboard_existing_config_overwrite(mock_paths):
+ """Config exists, user confirms overwrite — should reset to defaults."""
+ config_file, workspace_dir = mock_paths
+ config_file.write_text('{"existing": true}')
+
+ result = runner.invoke(app, ["onboard"], input="y\n")
+
+ assert result.exit_code == 0
+ assert "Config already exists" in result.stdout
+ assert "Config reset to defaults" in result.stdout
+ assert workspace_dir.exists()
+
+
+def test_onboard_existing_workspace_safe_create(mock_paths):
+ """Workspace exists — should not recreate, but still add missing templates."""
+ config_file, workspace_dir = mock_paths
+ workspace_dir.mkdir(parents=True)
+ config_file.write_text("{}")
+
+ result = runner.invoke(app, ["onboard"], input="n\n")
+
+ assert result.exit_code == 0
+ assert "Created workspace" not in result.stdout
+ assert "Created AGENTS.md" in result.stdout
+ assert (workspace_dir / "AGENTS.md").exists()
+
+
+def test_config_matches_github_copilot_codex_with_hyphen_prefix():
+ config = Config()
+ config.agents.defaults.model = "github-copilot/gpt-5.3-codex"
+
+ assert config.get_provider_name() == "github_copilot"
+
+
+def test_config_matches_openai_codex_with_hyphen_prefix():
+ config = Config()
+ config.agents.defaults.model = "openai-codex/gpt-5.1-codex"
+
+ assert config.get_provider_name() == "openai_codex"
+
+
+def test_find_by_model_prefers_explicit_prefix_over_generic_codex_keyword():
+ spec = find_by_model("github-copilot/gpt-5.3-codex")
+
+ assert spec is not None
+ assert spec.name == "github_copilot"
+
+
+def test_litellm_provider_canonicalizes_github_copilot_hyphen_prefix():
+ provider = LiteLLMProvider(default_model="github-copilot/gpt-5.3-codex")
+
+ resolved = provider._resolve_model("github-copilot/gpt-5.3-codex")
+
+ assert resolved == "github_copilot/gpt-5.3-codex"
+
+
+def test_openai_codex_strip_prefix_supports_hyphen_and_underscore():
+ assert _strip_model_prefix("openai-codex/gpt-5.1-codex") == "gpt-5.1-codex"
+ assert _strip_model_prefix("openai_codex/gpt-5.1-codex") == "gpt-5.1-codex"
+
+
+@pytest.fixture
+def mock_agent_runtime(tmp_path):
+ """Mock agent command dependencies for focused CLI tests."""
+ config = Config()
+ config.agents.defaults.workspace = str(tmp_path / "default-workspace")
+ cron_dir = tmp_path / "data" / "cron"
+
+ with patch("nanobot.config.loader.load_config", return_value=config) as mock_load_config, \
+ patch("nanobot.config.paths.get_cron_dir", return_value=cron_dir), \
+ patch("nanobot.cli.commands.sync_workspace_templates") as mock_sync_templates, \
+ patch("nanobot.cli.commands._make_provider", return_value=object()), \
+ patch("nanobot.cli.commands._print_agent_response") as mock_print_response, \
+ patch("nanobot.bus.queue.MessageBus"), \
+ patch("nanobot.cron.service.CronService"), \
+ patch("nanobot.agent.loop.AgentLoop") as mock_agent_loop_cls:
+
+ agent_loop = MagicMock()
+ agent_loop.channels_config = None
+ agent_loop.process_direct = AsyncMock(return_value="mock-response")
+ agent_loop.close_mcp = AsyncMock(return_value=None)
+ mock_agent_loop_cls.return_value = agent_loop
+
+ yield {
+ "config": config,
+ "load_config": mock_load_config,
+ "sync_templates": mock_sync_templates,
+ "agent_loop_cls": mock_agent_loop_cls,
+ "agent_loop": agent_loop,
+ "print_response": mock_print_response,
+ }
+
+
+def test_agent_help_shows_workspace_and_config_options():
+ result = runner.invoke(app, ["agent", "--help"])
+
+ assert result.exit_code == 0
+ assert "--workspace" in result.stdout
+ assert "-w" in result.stdout
+ assert "--config" in result.stdout
+ assert "-c" in result.stdout
+
+
+def test_agent_uses_default_config_when_no_workspace_or_config_flags(mock_agent_runtime):
+ result = runner.invoke(app, ["agent", "-m", "hello"])
+
+ assert result.exit_code == 0
+ assert mock_agent_runtime["load_config"].call_args.args == (None,)
+ assert mock_agent_runtime["sync_templates"].call_args.args == (
+ mock_agent_runtime["config"].workspace_path,
+ )
+ assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == (
+ mock_agent_runtime["config"].workspace_path
+ )
+ mock_agent_runtime["agent_loop"].process_direct.assert_awaited_once()
+ mock_agent_runtime["print_response"].assert_called_once_with("mock-response", render_markdown=True)
+
+
+def test_agent_uses_explicit_config_path(mock_agent_runtime, tmp_path: Path):
+ config_path = tmp_path / "agent-config.json"
+ config_path.write_text("{}")
+
+ result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_path)])
+
+ assert result.exit_code == 0
+ assert mock_agent_runtime["load_config"].call_args.args == (config_path.resolve(),)
+
+
+def test_agent_config_sets_active_path(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance" / "config.json"
+ config_file.parent.mkdir(parents=True)
+ config_file.write_text("{}")
+
+ config = Config()
+ seen: dict[str, Path] = {}
+
+ monkeypatch.setattr(
+ "nanobot.config.loader.set_config_path",
+ lambda path: seen.__setitem__("config_path", path),
+ )
+ monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+ monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: config_file.parent / "cron")
+ monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+ monkeypatch.setattr("nanobot.cli.commands._make_provider", lambda _config: object())
+ monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
+ monkeypatch.setattr("nanobot.cron.service.CronService", lambda _store: object())
+
+ class _FakeAgentLoop:
+ def __init__(self, *args, **kwargs) -> None:
+ pass
+
+ async def process_direct(self, *_args, **_kwargs) -> str:
+ return "ok"
+
+ async def close_mcp(self) -> None:
+ return None
+
+ monkeypatch.setattr("nanobot.agent.loop.AgentLoop", _FakeAgentLoop)
+ monkeypatch.setattr("nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None)
+
+ result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_file)])
+
+ assert result.exit_code == 0
+ assert seen["config_path"] == config_file.resolve()
+
+
+def test_agent_overrides_workspace_path(mock_agent_runtime):
+ workspace_path = Path("/tmp/agent-workspace")
+
+ result = runner.invoke(app, ["agent", "-m", "hello", "-w", str(workspace_path)])
+
+ assert result.exit_code == 0
+ assert mock_agent_runtime["config"].agents.defaults.workspace == str(workspace_path)
+ assert mock_agent_runtime["sync_templates"].call_args.args == (workspace_path,)
+ assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == workspace_path
+
+
+def test_agent_workspace_override_wins_over_config_workspace(mock_agent_runtime, tmp_path: Path):
+ config_path = tmp_path / "agent-config.json"
+ config_path.write_text("{}")
+ workspace_path = Path("/tmp/agent-workspace")
+
+ result = runner.invoke(
+ app,
+ ["agent", "-m", "hello", "-c", str(config_path), "-w", str(workspace_path)],
+ )
+
+ assert result.exit_code == 0
+ assert mock_agent_runtime["load_config"].call_args.args == (config_path.resolve(),)
+ assert mock_agent_runtime["config"].agents.defaults.workspace == str(workspace_path)
+ assert mock_agent_runtime["sync_templates"].call_args.args == (workspace_path,)
+ assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == workspace_path
+
+
+def test_gateway_uses_workspace_from_config_by_default(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance" / "config.json"
+ config_file.parent.mkdir(parents=True)
+ config_file.write_text("{}")
+
+ config = Config()
+ config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+ seen: dict[str, Path] = {}
+
+ monkeypatch.setattr(
+ "nanobot.config.loader.set_config_path",
+ lambda path: seen.__setitem__("config_path", path),
+ )
+ monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+ monkeypatch.setattr(
+ "nanobot.cli.commands.sync_workspace_templates",
+ lambda path: seen.__setitem__("workspace", path),
+ )
+ monkeypatch.setattr(
+ "nanobot.cli.commands._make_provider",
+ lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+ )
+
+ result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+ assert isinstance(result.exception, _StopGateway)
+ assert seen["config_path"] == config_file.resolve()
+ assert seen["workspace"] == Path(config.agents.defaults.workspace)
+
+
+def test_gateway_workspace_option_overrides_config(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance" / "config.json"
+ config_file.parent.mkdir(parents=True)
+ config_file.write_text("{}")
+
+ config = Config()
+ config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+ override = tmp_path / "override-workspace"
+ seen: dict[str, Path] = {}
+
+ monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+ monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+ monkeypatch.setattr(
+ "nanobot.cli.commands.sync_workspace_templates",
+ lambda path: seen.__setitem__("workspace", path),
+ )
+ monkeypatch.setattr(
+ "nanobot.cli.commands._make_provider",
+ lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+ )
+
+ result = runner.invoke(
+ app,
+ ["gateway", "--config", str(config_file), "--workspace", str(override)],
+ )
+
+ assert isinstance(result.exception, _StopGateway)
+ assert seen["workspace"] == override
+ assert config.workspace_path == override
+
+
+def test_gateway_uses_config_directory_for_cron_store(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance" / "config.json"
+ config_file.parent.mkdir(parents=True)
+ config_file.write_text("{}")
+
+ config = Config()
+ config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+ seen: dict[str, Path] = {}
+
+ monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+ monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+ monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: config_file.parent / "cron")
+ monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+ monkeypatch.setattr("nanobot.cli.commands._make_provider", lambda _config: object())
+ monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
+ monkeypatch.setattr("nanobot.session.manager.SessionManager", lambda _workspace: object())
+
+ class _StopCron:
+ def __init__(self, store_path: Path) -> None:
+ seen["cron_store"] = store_path
+ raise _StopGateway("stop")
+
+ monkeypatch.setattr("nanobot.cron.service.CronService", _StopCron)
+
+ result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+ assert isinstance(result.exception, _StopGateway)
+ assert seen["cron_store"] == config_file.parent / "cron" / "jobs.json"
diff --git a/nanobot/tests/test_config_paths.py b/nanobot/tests/test_config_paths.py
new file mode 100644
index 0000000..473a6c8
--- /dev/null
+++ b/nanobot/tests/test_config_paths.py
@@ -0,0 +1,42 @@
+from pathlib import Path
+
+from nanobot.config.paths import (
+ get_bridge_install_dir,
+ get_cli_history_path,
+ get_cron_dir,
+ get_data_dir,
+ get_legacy_sessions_dir,
+ get_logs_dir,
+ get_media_dir,
+ get_runtime_subdir,
+ get_workspace_path,
+)
+
+
+def test_runtime_dirs_follow_config_path(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance-a" / "config.json"
+ monkeypatch.setattr("nanobot.config.paths.get_config_path", lambda: config_file)
+
+ assert get_data_dir() == config_file.parent
+ assert get_runtime_subdir("cron") == config_file.parent / "cron"
+ assert get_cron_dir() == config_file.parent / "cron"
+ assert get_logs_dir() == config_file.parent / "logs"
+
+
+def test_media_dir_supports_channel_namespace(monkeypatch, tmp_path: Path) -> None:
+ config_file = tmp_path / "instance-b" / "config.json"
+ monkeypatch.setattr("nanobot.config.paths.get_config_path", lambda: config_file)
+
+ assert get_media_dir() == config_file.parent / "media"
+ assert get_media_dir("telegram") == config_file.parent / "media" / "telegram"
+
+
+def test_shared_and_legacy_paths_remain_global() -> None:
+ assert get_cli_history_path() == Path.home() / ".nanobot" / "history" / "cli_history"
+ assert get_bridge_install_dir() == Path.home() / ".nanobot" / "bridge"
+ assert get_legacy_sessions_dir() == Path.home() / ".nanobot" / "sessions"
+
+
+def test_workspace_path_is_explicitly_resolved() -> None:
+ assert get_workspace_path() == Path.home() / ".nanobot" / "workspace"
+ assert get_workspace_path("~/custom-workspace") == Path.home() / "custom-workspace"
diff --git a/nanobot/tests/test_consolidate_offset.py b/nanobot/tests/test_consolidate_offset.py
new file mode 100644
index 0000000..a3213dd
--- /dev/null
+++ b/nanobot/tests/test_consolidate_offset.py
@@ -0,0 +1,821 @@
+"""Test session management with cache-friendly message handling."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from pathlib import Path
+from nanobot.session.manager import Session, SessionManager
+
+# Test constants
+MEMORY_WINDOW = 50
+KEEP_COUNT = MEMORY_WINDOW // 2 # 25
+
+
+def create_session_with_messages(key: str, count: int, role: str = "user") -> Session:
+ """Create a session and add the specified number of messages.
+
+ Args:
+ key: Session identifier
+ count: Number of messages to add
+ role: Message role (default: "user")
+
+ Returns:
+ Session with the specified messages
+ """
+ session = Session(key=key)
+ for i in range(count):
+ session.add_message(role, f"msg{i}")
+ return session
+
+
+def assert_messages_content(messages: list, start_index: int, end_index: int) -> None:
+ """Assert that messages contain expected content from start to end index.
+
+ Args:
+ messages: List of message dictionaries
+ start_index: Expected first message index
+ end_index: Expected last message index
+ """
+ assert len(messages) > 0
+ assert messages[0]["content"] == f"msg{start_index}"
+ assert messages[-1]["content"] == f"msg{end_index}"
+
+
+def get_old_messages(session: Session, last_consolidated: int, keep_count: int) -> list:
+ """Extract messages that would be consolidated using the standard slice logic.
+
+ Args:
+ session: The session containing messages
+ last_consolidated: Index of last consolidated message
+ keep_count: Number of recent messages to keep
+
+ Returns:
+ List of messages that would be consolidated
+ """
+ return session.messages[last_consolidated:-keep_count]
+
+
+class TestSessionLastConsolidated:
+ """Test last_consolidated tracking to avoid duplicate processing."""
+
+ def test_initial_last_consolidated_zero(self) -> None:
+ """Test that new session starts with last_consolidated=0."""
+ session = Session(key="test:initial")
+ assert session.last_consolidated == 0
+
+ def test_last_consolidated_persistence(self, tmp_path) -> None:
+ """Test that last_consolidated persists across save/load."""
+ manager = SessionManager(Path(tmp_path))
+ session1 = create_session_with_messages("test:persist", 20)
+ session1.last_consolidated = 15
+ manager.save(session1)
+
+ session2 = manager.get_or_create("test:persist")
+ assert session2.last_consolidated == 15
+ assert len(session2.messages) == 20
+
+ def test_clear_resets_last_consolidated(self) -> None:
+ """Test that clear() resets last_consolidated to 0."""
+ session = create_session_with_messages("test:clear", 10)
+ session.last_consolidated = 5
+
+ session.clear()
+ assert len(session.messages) == 0
+ assert session.last_consolidated == 0
+
+
+class TestSessionImmutableHistory:
+ """Test Session message immutability for cache efficiency."""
+
+ def test_initial_state(self) -> None:
+ """Test that new session has empty messages list."""
+ session = Session(key="test:initial")
+ assert len(session.messages) == 0
+
+ def test_add_messages_appends_only(self) -> None:
+ """Test that adding messages only appends, never modifies."""
+ session = Session(key="test:preserve")
+ session.add_message("user", "msg1")
+ session.add_message("assistant", "resp1")
+ session.add_message("user", "msg2")
+ assert len(session.messages) == 3
+ assert session.messages[0]["content"] == "msg1"
+
+ def test_get_history_returns_most_recent(self) -> None:
+ """Test get_history returns the most recent messages."""
+ session = Session(key="test:history")
+ for i in range(10):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+
+ history = session.get_history(max_messages=6)
+ assert len(history) == 6
+ assert history[0]["content"] == "msg7"
+ assert history[-1]["content"] == "resp9"
+
+ def test_get_history_with_all_messages(self) -> None:
+ """Test get_history with max_messages larger than actual."""
+ session = create_session_with_messages("test:all", 5)
+ history = session.get_history(max_messages=100)
+ assert len(history) == 5
+ assert history[0]["content"] == "msg0"
+
+ def test_get_history_stable_for_same_session(self) -> None:
+ """Test that get_history returns same content for same max_messages."""
+ session = create_session_with_messages("test:stable", 20)
+ history1 = session.get_history(max_messages=10)
+ history2 = session.get_history(max_messages=10)
+ assert history1 == history2
+
+ def test_messages_list_never_modified(self) -> None:
+ """Test that messages list is never modified after creation."""
+ session = create_session_with_messages("test:immutable", 5)
+ original_len = len(session.messages)
+
+ session.get_history(max_messages=2)
+ assert len(session.messages) == original_len
+
+ for _ in range(10):
+ session.get_history(max_messages=3)
+ assert len(session.messages) == original_len
+
+
+class TestSessionPersistence:
+ """Test Session persistence and reload."""
+
+ @pytest.fixture
+ def temp_manager(self, tmp_path):
+ return SessionManager(Path(tmp_path))
+
+ def test_persistence_roundtrip(self, temp_manager):
+ """Test that messages persist across save/load."""
+ session1 = create_session_with_messages("test:persistence", 20)
+ temp_manager.save(session1)
+
+ session2 = temp_manager.get_or_create("test:persistence")
+ assert len(session2.messages) == 20
+ assert session2.messages[0]["content"] == "msg0"
+ assert session2.messages[-1]["content"] == "msg19"
+
+ def test_get_history_after_reload(self, temp_manager):
+ """Test that get_history works correctly after reload."""
+ session1 = create_session_with_messages("test:reload", 30)
+ temp_manager.save(session1)
+
+ session2 = temp_manager.get_or_create("test:reload")
+ history = session2.get_history(max_messages=10)
+ assert len(history) == 10
+ assert history[0]["content"] == "msg20"
+ assert history[-1]["content"] == "msg29"
+
+ def test_clear_resets_session(self, temp_manager):
+ """Test that clear() properly resets session."""
+ session = create_session_with_messages("test:clear", 10)
+ assert len(session.messages) == 10
+
+ session.clear()
+ assert len(session.messages) == 0
+
+
+class TestConsolidationTriggerConditions:
+ """Test consolidation trigger conditions and logic."""
+
+ def test_consolidation_needed_when_messages_exceed_window(self):
+ """Test consolidation logic: should trigger when messages > memory_window."""
+ session = create_session_with_messages("test:trigger", 60)
+
+ total_messages = len(session.messages)
+ messages_to_process = total_messages - session.last_consolidated
+
+ assert total_messages > MEMORY_WINDOW
+ assert messages_to_process > 0
+
+ expected_consolidate_count = total_messages - KEEP_COUNT
+ assert expected_consolidate_count == 35
+
+ def test_consolidation_skipped_when_within_keep_count(self):
+ """Test consolidation skipped when total messages <= keep_count."""
+ session = create_session_with_messages("test:skip", 20)
+
+ total_messages = len(session.messages)
+ assert total_messages <= KEEP_COUNT
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 0
+
+ def test_consolidation_skipped_when_no_new_messages(self):
+ """Test consolidation skipped when messages_to_process <= 0."""
+ session = create_session_with_messages("test:already_consolidated", 40)
+ session.last_consolidated = len(session.messages) - KEEP_COUNT # 15
+
+ # Add a few more messages
+ for i in range(40, 42):
+ session.add_message("user", f"msg{i}")
+
+ total_messages = len(session.messages)
+ messages_to_process = total_messages - session.last_consolidated
+ assert messages_to_process > 0
+
+ # Simulate last_consolidated catching up
+ session.last_consolidated = total_messages - KEEP_COUNT
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 0
+
+
+class TestLastConsolidatedEdgeCases:
+ """Test last_consolidated edge cases and data corruption scenarios."""
+
+ def test_last_consolidated_exceeds_message_count(self):
+ """Test behavior when last_consolidated > len(messages) (data corruption)."""
+ session = create_session_with_messages("test:corruption", 10)
+ session.last_consolidated = 20
+
+ total_messages = len(session.messages)
+ messages_to_process = total_messages - session.last_consolidated
+ assert messages_to_process <= 0
+
+ old_messages = get_old_messages(session, session.last_consolidated, 5)
+ assert len(old_messages) == 0
+
+ def test_last_consolidated_negative_value(self):
+ """Test behavior with negative last_consolidated (invalid state)."""
+ session = create_session_with_messages("test:negative", 10)
+ session.last_consolidated = -5
+
+ keep_count = 3
+ old_messages = get_old_messages(session, session.last_consolidated, keep_count)
+
+ # messages[-5:-3] with 10 messages gives indices 5,6
+ assert len(old_messages) == 2
+ assert old_messages[0]["content"] == "msg5"
+ assert old_messages[-1]["content"] == "msg6"
+
+ def test_messages_added_after_consolidation(self):
+ """Test correct behavior when new messages arrive after consolidation."""
+ session = create_session_with_messages("test:new_messages", 40)
+ session.last_consolidated = len(session.messages) - KEEP_COUNT # 15
+
+ # Add new messages after consolidation
+ for i in range(40, 50):
+ session.add_message("user", f"msg{i}")
+
+ total_messages = len(session.messages)
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ expected_consolidate_count = total_messages - KEEP_COUNT - session.last_consolidated
+
+ assert len(old_messages) == expected_consolidate_count
+ assert_messages_content(old_messages, 15, 24)
+
+ def test_slice_behavior_when_indices_overlap(self):
+ """Test slice behavior when last_consolidated >= total - keep_count."""
+ session = create_session_with_messages("test:overlap", 30)
+ session.last_consolidated = 12
+
+ old_messages = get_old_messages(session, session.last_consolidated, 20)
+ assert len(old_messages) == 0
+
+
+class TestArchiveAllMode:
+ """Test archive_all mode (used by /new command)."""
+
+ def test_archive_all_consolidates_everything(self):
+ """Test archive_all=True consolidates all messages."""
+ session = create_session_with_messages("test:archive_all", 50)
+
+ archive_all = True
+ if archive_all:
+ old_messages = session.messages
+ assert len(old_messages) == 50
+
+ assert session.last_consolidated == 0
+
+ def test_archive_all_resets_last_consolidated(self):
+ """Test that archive_all mode resets last_consolidated to 0."""
+ session = create_session_with_messages("test:reset", 40)
+ session.last_consolidated = 15
+
+ archive_all = True
+ if archive_all:
+ session.last_consolidated = 0
+
+ assert session.last_consolidated == 0
+ assert len(session.messages) == 40
+
+ def test_archive_all_vs_normal_consolidation(self):
+ """Test difference between archive_all and normal consolidation."""
+ # Normal consolidation
+ session1 = create_session_with_messages("test:normal", 60)
+ session1.last_consolidated = len(session1.messages) - KEEP_COUNT
+
+ # archive_all mode
+ session2 = create_session_with_messages("test:all", 60)
+ session2.last_consolidated = 0
+
+ assert session1.last_consolidated == 35
+ assert len(session1.messages) == 60
+ assert session2.last_consolidated == 0
+ assert len(session2.messages) == 60
+
+
+class TestCacheImmutability:
+ """Test that consolidation doesn't modify session.messages (cache safety)."""
+
+ def test_consolidation_does_not_modify_messages_list(self):
+ """Test that consolidation leaves messages list unchanged."""
+ session = create_session_with_messages("test:immutable", 50)
+
+ original_messages = session.messages.copy()
+ original_len = len(session.messages)
+ session.last_consolidated = original_len - KEEP_COUNT
+
+ assert len(session.messages) == original_len
+ assert session.messages == original_messages
+
+ def test_get_history_does_not_modify_messages(self):
+ """Test that get_history doesn't modify messages list."""
+ session = create_session_with_messages("test:history_immutable", 40)
+ original_messages = [m.copy() for m in session.messages]
+
+ for _ in range(5):
+ history = session.get_history(max_messages=10)
+ assert len(history) == 10
+
+ assert len(session.messages) == 40
+ for i, msg in enumerate(session.messages):
+ assert msg["content"] == original_messages[i]["content"]
+
+ def test_consolidation_only_updates_last_consolidated(self):
+ """Test that consolidation only updates last_consolidated field."""
+ session = create_session_with_messages("test:field_only", 60)
+
+ original_messages = session.messages.copy()
+ original_key = session.key
+ original_metadata = session.metadata.copy()
+
+ session.last_consolidated = len(session.messages) - KEEP_COUNT
+
+ assert session.messages == original_messages
+ assert session.key == original_key
+ assert session.metadata == original_metadata
+ assert session.last_consolidated == 35
+
+
+class TestSliceLogic:
+ """Test the slice logic: messages[last_consolidated:-keep_count]."""
+
+ def test_slice_extracts_correct_range(self):
+ """Test that slice extracts the correct message range."""
+ session = create_session_with_messages("test:slice", 60)
+
+ old_messages = get_old_messages(session, 0, KEEP_COUNT)
+
+ assert len(old_messages) == 35
+ assert_messages_content(old_messages, 0, 34)
+
+ remaining = session.messages[-KEEP_COUNT:]
+ assert len(remaining) == 25
+ assert_messages_content(remaining, 35, 59)
+
+ def test_slice_with_partial_consolidation(self):
+ """Test slice when some messages already consolidated."""
+ session = create_session_with_messages("test:partial", 70)
+
+ last_consolidated = 30
+ old_messages = get_old_messages(session, last_consolidated, KEEP_COUNT)
+
+ assert len(old_messages) == 15
+ assert_messages_content(old_messages, 30, 44)
+
+ def test_slice_with_various_keep_counts(self):
+ """Test slice behavior with different keep_count values."""
+ session = create_session_with_messages("test:keep_counts", 50)
+
+ test_cases = [(10, 40), (20, 30), (30, 20), (40, 10)]
+
+ for keep_count, expected_count in test_cases:
+ old_messages = session.messages[0:-keep_count]
+ assert len(old_messages) == expected_count
+
+ def test_slice_when_keep_count_exceeds_messages(self):
+ """Test slice when keep_count > len(messages)."""
+ session = create_session_with_messages("test:exceed", 10)
+
+ old_messages = session.messages[0:-20]
+ assert len(old_messages) == 0
+
+
+class TestEmptyAndBoundarySessions:
+ """Test empty sessions and boundary conditions."""
+
+ def test_empty_session_consolidation(self):
+ """Test consolidation behavior with empty session."""
+ session = Session(key="test:empty")
+
+ assert len(session.messages) == 0
+ assert session.last_consolidated == 0
+
+ messages_to_process = len(session.messages) - session.last_consolidated
+ assert messages_to_process == 0
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 0
+
+ def test_single_message_session(self):
+ """Test consolidation with single message."""
+ session = Session(key="test:single")
+ session.add_message("user", "only message")
+
+ assert len(session.messages) == 1
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 0
+
+ def test_exactly_keep_count_messages(self):
+ """Test session with exactly keep_count messages."""
+ session = create_session_with_messages("test:exact", KEEP_COUNT)
+
+ assert len(session.messages) == KEEP_COUNT
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 0
+
+ def test_just_over_keep_count(self):
+ """Test session with one message over keep_count."""
+ session = create_session_with_messages("test:over", KEEP_COUNT + 1)
+
+ assert len(session.messages) == 26
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 1
+ assert old_messages[0]["content"] == "msg0"
+
+ def test_very_large_session(self):
+ """Test consolidation with very large message count."""
+ session = create_session_with_messages("test:large", 1000)
+
+ assert len(session.messages) == 1000
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+ assert len(old_messages) == 975
+ assert_messages_content(old_messages, 0, 974)
+
+ remaining = session.messages[-KEEP_COUNT:]
+ assert len(remaining) == 25
+ assert_messages_content(remaining, 975, 999)
+
+ def test_session_with_gaps_in_consolidation(self):
+ """Test session with potential gaps in consolidation history."""
+ session = create_session_with_messages("test:gaps", 50)
+ session.last_consolidated = 10
+
+ # Add more messages
+ for i in range(50, 60):
+ session.add_message("user", f"msg{i}")
+
+ old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+
+ expected_count = 60 - KEEP_COUNT - 10
+ assert len(old_messages) == expected_count
+ assert_messages_content(old_messages, 10, 34)
+
+
+class TestConsolidationDeduplicationGuard:
+ """Test that consolidation tasks are deduplicated and serialized."""
+
+ @pytest.mark.asyncio
+ async def test_consolidation_guard_prevents_duplicate_tasks(self, tmp_path: Path) -> None:
+ """Concurrent messages above memory_window spawn only one consolidation task."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(15):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ consolidation_calls = 0
+
+ async def _fake_consolidate(_session, archive_all: bool = False) -> None:
+ nonlocal consolidation_calls
+ consolidation_calls += 1
+ await asyncio.sleep(0.05)
+
+ loop._consolidate_memory = _fake_consolidate # type: ignore[method-assign]
+
+ msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="hello")
+ await loop._process_message(msg)
+ await loop._process_message(msg)
+ await asyncio.sleep(0.1)
+
+ assert consolidation_calls == 1, (
+ f"Expected exactly 1 consolidation, got {consolidation_calls}"
+ )
+
+ @pytest.mark.asyncio
+ async def test_new_command_guard_prevents_concurrent_consolidation(
+ self, tmp_path: Path
+ ) -> None:
+ """/new command does not run consolidation concurrently with in-flight consolidation."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(15):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ consolidation_calls = 0
+ active = 0
+ max_active = 0
+
+ async def _fake_consolidate(_session, archive_all: bool = False) -> None:
+ nonlocal consolidation_calls, active, max_active
+ consolidation_calls += 1
+ active += 1
+ max_active = max(max_active, active)
+ await asyncio.sleep(0.05)
+ active -= 1
+
+ loop._consolidate_memory = _fake_consolidate # type: ignore[method-assign]
+
+ msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="hello")
+ await loop._process_message(msg)
+
+ new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+ await loop._process_message(new_msg)
+ await asyncio.sleep(0.1)
+
+ assert consolidation_calls == 2, (
+ f"Expected normal + /new consolidations, got {consolidation_calls}"
+ )
+ assert max_active == 1, (
+ f"Expected serialized consolidation, observed concurrency={max_active}"
+ )
+
+ @pytest.mark.asyncio
+ async def test_consolidation_tasks_are_referenced(self, tmp_path: Path) -> None:
+ """create_task results are tracked in _consolidation_tasks while in flight."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(15):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ started = asyncio.Event()
+
+ async def _slow_consolidate(_session, archive_all: bool = False) -> None:
+ started.set()
+ await asyncio.sleep(0.1)
+
+ loop._consolidate_memory = _slow_consolidate # type: ignore[method-assign]
+
+ msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="hello")
+ await loop._process_message(msg)
+
+ await started.wait()
+ assert len(loop._consolidation_tasks) == 1, "Task must be referenced while in-flight"
+
+ await asyncio.sleep(0.15)
+ assert len(loop._consolidation_tasks) == 0, (
+ "Task reference must be removed after completion"
+ )
+
+ @pytest.mark.asyncio
+ async def test_new_waits_for_inflight_consolidation_and_preserves_messages(
+ self, tmp_path: Path
+ ) -> None:
+ """/new waits for in-flight consolidation and archives before clear."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(15):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ started = asyncio.Event()
+ release = asyncio.Event()
+ archived_count = 0
+
+ async def _fake_consolidate(sess, archive_all: bool = False) -> bool:
+ nonlocal archived_count
+ if archive_all:
+ archived_count = len(sess.messages)
+ return True
+ started.set()
+ await release.wait()
+ return True
+
+ loop._consolidate_memory = _fake_consolidate # type: ignore[method-assign]
+
+ msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="hello")
+ await loop._process_message(msg)
+ await started.wait()
+
+ new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+ pending_new = asyncio.create_task(loop._process_message(new_msg))
+
+ await asyncio.sleep(0.02)
+ assert not pending_new.done(), "/new should wait while consolidation is in-flight"
+
+ release.set()
+ response = await pending_new
+ assert response is not None
+ assert "new session started" in response.content.lower()
+ assert archived_count > 0, "Expected /new archival to process a non-empty snapshot"
+
+ session_after = loop.sessions.get_or_create("cli:test")
+ assert session_after.messages == [], "Session should be cleared after successful archival"
+
+ @pytest.mark.asyncio
+ async def test_new_does_not_clear_session_when_archive_fails(self, tmp_path: Path) -> None:
+ """/new must keep session data if archive step reports failure."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(5):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+ before_count = len(session.messages)
+
+ async def _failing_consolidate(sess, archive_all: bool = False) -> bool:
+ if archive_all:
+ return False
+ return True
+
+ loop._consolidate_memory = _failing_consolidate # type: ignore[method-assign]
+
+ new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+ response = await loop._process_message(new_msg)
+
+ assert response is not None
+ assert "failed" in response.content.lower()
+ session_after = loop.sessions.get_or_create("cli:test")
+ assert len(session_after.messages) == before_count, (
+ "Session must remain intact when /new archival fails"
+ )
+
+ @pytest.mark.asyncio
+ async def test_new_archives_only_unconsolidated_messages_after_inflight_task(
+ self, tmp_path: Path
+ ) -> None:
+ """/new should archive only messages not yet consolidated by prior task."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(15):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ started = asyncio.Event()
+ release = asyncio.Event()
+ archived_count = -1
+
+ async def _fake_consolidate(sess, archive_all: bool = False) -> bool:
+ nonlocal archived_count
+ if archive_all:
+ archived_count = len(sess.messages)
+ return True
+
+ started.set()
+ await release.wait()
+ sess.last_consolidated = len(sess.messages) - 3
+ return True
+
+ loop._consolidate_memory = _fake_consolidate # type: ignore[method-assign]
+
+ msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="hello")
+ await loop._process_message(msg)
+ await started.wait()
+
+ new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+ pending_new = asyncio.create_task(loop._process_message(new_msg))
+ await asyncio.sleep(0.02)
+ assert not pending_new.done()
+
+ release.set()
+ response = await pending_new
+
+ assert response is not None
+ assert "new session started" in response.content.lower()
+ assert archived_count == 3, (
+ f"Expected only unconsolidated tail to archive, got {archived_count}"
+ )
+
+ @pytest.mark.asyncio
+ async def test_new_clears_session_and_responds(self, tmp_path: Path) -> None:
+ """/new clears session and returns confirmation."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.events import InboundMessage
+ from nanobot.bus.queue import MessageBus
+ from nanobot.providers.base import LLMResponse
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ loop = AgentLoop(
+ bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10
+ )
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ session = loop.sessions.get_or_create("cli:test")
+ for i in range(3):
+ session.add_message("user", f"msg{i}")
+ session.add_message("assistant", f"resp{i}")
+ loop.sessions.save(session)
+
+ async def _ok_consolidate(sess, archive_all: bool = False) -> bool:
+ return True
+
+ loop._consolidate_memory = _ok_consolidate # type: ignore[method-assign]
+
+ new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+ response = await loop._process_message(new_msg)
+
+ assert response is not None
+ assert "new session started" in response.content.lower()
+ assert loop.sessions.get_or_create("cli:test").messages == []
diff --git a/nanobot/tests/test_context_prompt_cache.py b/nanobot/tests/test_context_prompt_cache.py
new file mode 100644
index 0000000..6eb4b4f
--- /dev/null
+++ b/nanobot/tests/test_context_prompt_cache.py
@@ -0,0 +1,73 @@
+"""Tests for cache-friendly prompt construction."""
+
+from __future__ import annotations
+
+from datetime import datetime as real_datetime
+from importlib.resources import files as pkg_files
+from pathlib import Path
+import datetime as datetime_module
+
+from nanobot.agent.context import ContextBuilder
+
+
+class _FakeDatetime(real_datetime):
+ current = real_datetime(2026, 2, 24, 13, 59)
+
+ @classmethod
+ def now(cls, tz=None): # type: ignore[override]
+ return cls.current
+
+
+def _make_workspace(tmp_path: Path) -> Path:
+ workspace = tmp_path / "workspace"
+ workspace.mkdir(parents=True)
+ return workspace
+
+
+def test_bootstrap_files_are_backed_by_templates() -> None:
+ template_dir = pkg_files("nanobot") / "templates"
+
+ for filename in ContextBuilder.BOOTSTRAP_FILES:
+ assert (template_dir / filename).is_file(), f"missing bootstrap template: {filename}"
+
+
+def test_system_prompt_stays_stable_when_clock_changes(tmp_path, monkeypatch) -> None:
+ """System prompt should not change just because wall clock minute changes."""
+ monkeypatch.setattr(datetime_module, "datetime", _FakeDatetime)
+
+ workspace = _make_workspace(tmp_path)
+ builder = ContextBuilder(workspace)
+
+ _FakeDatetime.current = real_datetime(2026, 2, 24, 13, 59)
+ prompt1 = builder.build_system_prompt()
+
+ _FakeDatetime.current = real_datetime(2026, 2, 24, 14, 0)
+ prompt2 = builder.build_system_prompt()
+
+ assert prompt1 == prompt2
+
+
+def test_runtime_context_is_separate_untrusted_user_message(tmp_path) -> None:
+ """Runtime metadata should be merged with the user message."""
+ workspace = _make_workspace(tmp_path)
+ builder = ContextBuilder(workspace)
+
+ messages = builder.build_messages(
+ history=[],
+ current_message="Return exactly: OK",
+ channel="cli",
+ chat_id="direct",
+ )
+
+ assert messages[0]["role"] == "system"
+ assert "## Current Session" not in messages[0]["content"]
+
+ # Runtime context is now merged with user message into a single message
+ assert messages[-1]["role"] == "user"
+ user_content = messages[-1]["content"]
+ assert isinstance(user_content, str)
+ assert ContextBuilder._RUNTIME_CONTEXT_TAG in user_content
+ assert "Current Time:" in user_content
+ assert "Channel: cli" in user_content
+ assert "Chat ID: direct" in user_content
+ assert "Return exactly: OK" in user_content
diff --git a/nanobot/tests/test_cron_service.py b/nanobot/tests/test_cron_service.py
new file mode 100644
index 0000000..9631da5
--- /dev/null
+++ b/nanobot/tests/test_cron_service.py
@@ -0,0 +1,61 @@
+import asyncio
+
+import pytest
+
+from nanobot.cron.service import CronService
+from nanobot.cron.types import CronSchedule
+
+
+def test_add_job_rejects_unknown_timezone(tmp_path) -> None:
+ service = CronService(tmp_path / "cron" / "jobs.json")
+
+ with pytest.raises(ValueError, match="unknown timezone 'America/Vancovuer'"):
+ service.add_job(
+ name="tz typo",
+ schedule=CronSchedule(kind="cron", expr="0 9 * * *", tz="America/Vancovuer"),
+ message="hello",
+ )
+
+ assert service.list_jobs(include_disabled=True) == []
+
+
+def test_add_job_accepts_valid_timezone(tmp_path) -> None:
+ service = CronService(tmp_path / "cron" / "jobs.json")
+
+ job = service.add_job(
+ name="tz ok",
+ schedule=CronSchedule(kind="cron", expr="0 9 * * *", tz="America/Vancouver"),
+ message="hello",
+ )
+
+ assert job.schedule.tz == "America/Vancouver"
+ assert job.state.next_run_at_ms is not None
+
+
+@pytest.mark.asyncio
+async def test_running_service_honors_external_disable(tmp_path) -> None:
+ store_path = tmp_path / "cron" / "jobs.json"
+ called: list[str] = []
+
+ async def on_job(job) -> None:
+ called.append(job.id)
+
+ service = CronService(store_path, on_job=on_job)
+ job = service.add_job(
+ name="external-disable",
+ schedule=CronSchedule(kind="every", every_ms=200),
+ message="hello",
+ )
+ await service.start()
+ try:
+ # Wait slightly to ensure file mtime is definitively different
+ await asyncio.sleep(0.05)
+ external = CronService(store_path)
+ updated = external.enable_job(job.id, enabled=False)
+ assert updated is not None
+ assert updated.enabled is False
+
+ await asyncio.sleep(0.35)
+ assert called == []
+ finally:
+ service.stop()
diff --git a/nanobot/tests/test_dingtalk_channel.py b/nanobot/tests/test_dingtalk_channel.py
new file mode 100644
index 0000000..7595a33
--- /dev/null
+++ b/nanobot/tests/test_dingtalk_channel.py
@@ -0,0 +1,66 @@
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.dingtalk import DingTalkChannel
+from nanobot.config.schema import DingTalkConfig
+
+
+class _FakeResponse:
+ def __init__(self, status_code: int = 200, json_body: dict | None = None) -> None:
+ self.status_code = status_code
+ self._json_body = json_body or {}
+ self.text = "{}"
+
+ def json(self) -> dict:
+ return self._json_body
+
+
+class _FakeHttp:
+ def __init__(self) -> None:
+ self.calls: list[dict] = []
+
+ async def post(self, url: str, json=None, headers=None):
+ self.calls.append({"url": url, "json": json, "headers": headers})
+ return _FakeResponse()
+
+
+@pytest.mark.asyncio
+async def test_group_message_keeps_sender_id_and_routes_chat_id() -> None:
+ config = DingTalkConfig(client_id="app", client_secret="secret", allow_from=["user1"])
+ bus = MessageBus()
+ channel = DingTalkChannel(config, bus)
+
+ await channel._on_message(
+ "hello",
+ sender_id="user1",
+ sender_name="Alice",
+ conversation_type="2",
+ conversation_id="conv123",
+ )
+
+ msg = await bus.consume_inbound()
+ assert msg.sender_id == "user1"
+ assert msg.chat_id == "group:conv123"
+ assert msg.metadata["conversation_type"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_group_send_uses_group_messages_api() -> None:
+ config = DingTalkConfig(client_id="app", client_secret="secret", allow_from=["*"])
+ channel = DingTalkChannel(config, MessageBus())
+ channel._http = _FakeHttp()
+
+ ok = await channel._send_batch_message(
+ "token",
+ "group:conv123",
+ "sampleMarkdown",
+ {"text": "hello", "title": "Nanobot Reply"},
+ )
+
+ assert ok is True
+ call = channel._http.calls[0]
+ assert call["url"] == "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
+ assert call["json"]["openConversationId"] == "conv123"
+ assert call["json"]["msgKey"] == "sampleMarkdown"
diff --git a/nanobot/tests/test_docker.sh b/nanobot/tests/test_docker.sh
new file mode 100644
index 0000000..1e55133
--- /dev/null
+++ b/nanobot/tests/test_docker.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.." || exit 1
+
+IMAGE_NAME="nanobot-test"
+
+echo "=== Building Docker image ==="
+docker build -t "$IMAGE_NAME" .
+
+echo ""
+echo "=== Running 'nanobot onboard' ==="
+docker run --name nanobot-test-run "$IMAGE_NAME" onboard
+
+echo ""
+echo "=== Running 'nanobot status' ==="
+STATUS_OUTPUT=$(docker commit nanobot-test-run nanobot-test-onboarded > /dev/null && \
+ docker run --rm nanobot-test-onboarded status 2>&1) || true
+
+echo "$STATUS_OUTPUT"
+
+echo ""
+echo "=== Validating output ==="
+PASS=true
+
+check() {
+ if echo "$STATUS_OUTPUT" | grep -q "$1"; then
+ echo " PASS: found '$1'"
+ else
+ echo " FAIL: missing '$1'"
+ PASS=false
+ fi
+}
+
+check "nanobot Status"
+check "Config:"
+check "Workspace:"
+check "Model:"
+check "OpenRouter API:"
+check "Anthropic API:"
+check "OpenAI API:"
+
+echo ""
+if $PASS; then
+ echo "=== All checks passed ==="
+else
+ echo "=== Some checks FAILED ==="
+ exit 1
+fi
+
+# Cleanup
+echo ""
+echo "=== Cleanup ==="
+docker rm -f nanobot-test-run 2>/dev/null || true
+docker rmi -f nanobot-test-onboarded 2>/dev/null || true
+docker rmi -f "$IMAGE_NAME" 2>/dev/null || true
+echo "Done."
diff --git a/nanobot/tests/test_email_channel.py b/nanobot/tests/test_email_channel.py
new file mode 100644
index 0000000..adf35a8
--- /dev/null
+++ b/nanobot/tests/test_email_channel.py
@@ -0,0 +1,368 @@
+from email.message import EmailMessage
+from datetime import date
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.email import EmailChannel
+from nanobot.config.schema import EmailConfig
+
+
+def _make_config() -> EmailConfig:
+ return EmailConfig(
+ enabled=True,
+ consent_granted=True,
+ imap_host="imap.example.com",
+ imap_port=993,
+ imap_username="bot@example.com",
+ imap_password="secret",
+ smtp_host="smtp.example.com",
+ smtp_port=587,
+ smtp_username="bot@example.com",
+ smtp_password="secret",
+ mark_seen=True,
+ )
+
+
+def _make_raw_email(
+ from_addr: str = "alice@example.com",
+ subject: str = "Hello",
+ body: str = "This is the body.",
+) -> bytes:
+ msg = EmailMessage()
+ msg["From"] = from_addr
+ msg["To"] = "bot@example.com"
+ msg["Subject"] = subject
+ msg["Message-ID"] = ""
+ msg.set_content(body)
+ return msg.as_bytes()
+
+
+def test_fetch_new_messages_parses_unseen_and_marks_seen(monkeypatch) -> None:
+ raw = _make_raw_email(subject="Invoice", body="Please pay")
+
+ class FakeIMAP:
+ def __init__(self) -> None:
+ self.store_calls: list[tuple[bytes, str, str]] = []
+
+ def login(self, _user: str, _pw: str):
+ return "OK", [b"logged in"]
+
+ def select(self, _mailbox: str):
+ return "OK", [b"1"]
+
+ def search(self, *_args):
+ return "OK", [b"1"]
+
+ def fetch(self, _imap_id: bytes, _parts: str):
+ return "OK", [(b"1 (UID 123 BODY[] {200})", raw), b")"]
+
+ def store(self, imap_id: bytes, op: str, flags: str):
+ self.store_calls.append((imap_id, op, flags))
+ return "OK", [b""]
+
+ def logout(self):
+ return "BYE", [b""]
+
+ fake = FakeIMAP()
+ monkeypatch.setattr("nanobot.channels.email.imaplib.IMAP4_SSL", lambda _h, _p: fake)
+
+ channel = EmailChannel(_make_config(), MessageBus())
+ items = channel._fetch_new_messages()
+
+ assert len(items) == 1
+ assert items[0]["sender"] == "alice@example.com"
+ assert items[0]["subject"] == "Invoice"
+ assert "Please pay" in items[0]["content"]
+ assert fake.store_calls == [(b"1", "+FLAGS", "\\Seen")]
+
+ # Same UID should be deduped in-process.
+ items_again = channel._fetch_new_messages()
+ assert items_again == []
+
+
+def test_extract_text_body_falls_back_to_html() -> None:
+ msg = EmailMessage()
+ msg["From"] = "alice@example.com"
+ msg["To"] = "bot@example.com"
+ msg["Subject"] = "HTML only"
+ msg.add_alternative("Hello
world
", subtype="html")
+
+ text = EmailChannel._extract_text_body(msg)
+ assert "Hello" in text
+ assert "world" in text
+
+
+@pytest.mark.asyncio
+async def test_start_returns_immediately_without_consent(monkeypatch) -> None:
+ cfg = _make_config()
+ cfg.consent_granted = False
+ channel = EmailChannel(cfg, MessageBus())
+
+ called = {"fetch": False}
+
+ def _fake_fetch():
+ called["fetch"] = True
+ return []
+
+ monkeypatch.setattr(channel, "_fetch_new_messages", _fake_fetch)
+ await channel.start()
+ assert channel.is_running is False
+ assert called["fetch"] is False
+
+
+@pytest.mark.asyncio
+async def test_send_uses_smtp_and_reply_subject(monkeypatch) -> None:
+ class FakeSMTP:
+ def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+ self.timeout = timeout
+ self.started_tls = False
+ self.logged_in = False
+ self.sent_messages: list[EmailMessage] = []
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def starttls(self, context=None):
+ self.started_tls = True
+
+ def login(self, _user: str, _pw: str):
+ self.logged_in = True
+
+ def send_message(self, msg: EmailMessage):
+ self.sent_messages.append(msg)
+
+ fake_instances: list[FakeSMTP] = []
+
+ def _smtp_factory(host: str, port: int, timeout: int = 30):
+ instance = FakeSMTP(host, port, timeout=timeout)
+ fake_instances.append(instance)
+ return instance
+
+ monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+ channel = EmailChannel(_make_config(), MessageBus())
+ channel._last_subject_by_chat["alice@example.com"] = "Invoice #42"
+ channel._last_message_id_by_chat["alice@example.com"] = ""
+
+ await channel.send(
+ OutboundMessage(
+ channel="email",
+ chat_id="alice@example.com",
+ content="Acknowledged.",
+ )
+ )
+
+ assert len(fake_instances) == 1
+ smtp = fake_instances[0]
+ assert smtp.started_tls is True
+ assert smtp.logged_in is True
+ assert len(smtp.sent_messages) == 1
+ sent = smtp.sent_messages[0]
+ assert sent["Subject"] == "Re: Invoice #42"
+ assert sent["To"] == "alice@example.com"
+ assert sent["In-Reply-To"] == ""
+
+
+@pytest.mark.asyncio
+async def test_send_skips_reply_when_auto_reply_disabled(monkeypatch) -> None:
+ """When auto_reply_enabled=False, replies should be skipped but proactive sends allowed."""
+ class FakeSMTP:
+ def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+ self.sent_messages: list[EmailMessage] = []
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def starttls(self, context=None):
+ return None
+
+ def login(self, _user: str, _pw: str):
+ return None
+
+ def send_message(self, msg: EmailMessage):
+ self.sent_messages.append(msg)
+
+ fake_instances: list[FakeSMTP] = []
+
+ def _smtp_factory(host: str, port: int, timeout: int = 30):
+ instance = FakeSMTP(host, port, timeout=timeout)
+ fake_instances.append(instance)
+ return instance
+
+ monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+ cfg = _make_config()
+ cfg.auto_reply_enabled = False
+ channel = EmailChannel(cfg, MessageBus())
+
+ # Mark alice as someone who sent us an email (making this a "reply")
+ channel._last_subject_by_chat["alice@example.com"] = "Previous email"
+
+ # Reply should be skipped (auto_reply_enabled=False)
+ await channel.send(
+ OutboundMessage(
+ channel="email",
+ chat_id="alice@example.com",
+ content="Should not send.",
+ )
+ )
+ assert fake_instances == []
+
+ # Reply with force_send=True should be sent
+ await channel.send(
+ OutboundMessage(
+ channel="email",
+ chat_id="alice@example.com",
+ content="Force send.",
+ metadata={"force_send": True},
+ )
+ )
+ assert len(fake_instances) == 1
+ assert len(fake_instances[0].sent_messages) == 1
+
+
+@pytest.mark.asyncio
+async def test_send_proactive_email_when_auto_reply_disabled(monkeypatch) -> None:
+ """Proactive emails (not replies) should be sent even when auto_reply_enabled=False."""
+ class FakeSMTP:
+ def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+ self.sent_messages: list[EmailMessage] = []
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def starttls(self, context=None):
+ return None
+
+ def login(self, _user: str, _pw: str):
+ return None
+
+ def send_message(self, msg: EmailMessage):
+ self.sent_messages.append(msg)
+
+ fake_instances: list[FakeSMTP] = []
+
+ def _smtp_factory(host: str, port: int, timeout: int = 30):
+ instance = FakeSMTP(host, port, timeout=timeout)
+ fake_instances.append(instance)
+ return instance
+
+ monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+ cfg = _make_config()
+ cfg.auto_reply_enabled = False
+ channel = EmailChannel(cfg, MessageBus())
+
+ # bob@example.com has never sent us an email (proactive send)
+ # This should be sent even with auto_reply_enabled=False
+ await channel.send(
+ OutboundMessage(
+ channel="email",
+ chat_id="bob@example.com",
+ content="Hello, this is a proactive email.",
+ )
+ )
+ assert len(fake_instances) == 1
+ assert len(fake_instances[0].sent_messages) == 1
+ sent = fake_instances[0].sent_messages[0]
+ assert sent["To"] == "bob@example.com"
+
+
+@pytest.mark.asyncio
+async def test_send_skips_when_consent_not_granted(monkeypatch) -> None:
+ class FakeSMTP:
+ def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+ self.sent_messages: list[EmailMessage] = []
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def starttls(self, context=None):
+ return None
+
+ def login(self, _user: str, _pw: str):
+ return None
+
+ def send_message(self, msg: EmailMessage):
+ self.sent_messages.append(msg)
+
+ called = {"smtp": False}
+
+ def _smtp_factory(host: str, port: int, timeout: int = 30):
+ called["smtp"] = True
+ return FakeSMTP(host, port, timeout=timeout)
+
+ monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+ cfg = _make_config()
+ cfg.consent_granted = False
+ channel = EmailChannel(cfg, MessageBus())
+ await channel.send(
+ OutboundMessage(
+ channel="email",
+ chat_id="alice@example.com",
+ content="Should not send.",
+ metadata={"force_send": True},
+ )
+ )
+ assert called["smtp"] is False
+
+
+def test_fetch_messages_between_dates_uses_imap_since_before_without_mark_seen(monkeypatch) -> None:
+ raw = _make_raw_email(subject="Status", body="Yesterday update")
+
+ class FakeIMAP:
+ def __init__(self) -> None:
+ self.search_args = None
+ self.store_calls: list[tuple[bytes, str, str]] = []
+
+ def login(self, _user: str, _pw: str):
+ return "OK", [b"logged in"]
+
+ def select(self, _mailbox: str):
+ return "OK", [b"1"]
+
+ def search(self, *_args):
+ self.search_args = _args
+ return "OK", [b"5"]
+
+ def fetch(self, _imap_id: bytes, _parts: str):
+ return "OK", [(b"5 (UID 999 BODY[] {200})", raw), b")"]
+
+ def store(self, imap_id: bytes, op: str, flags: str):
+ self.store_calls.append((imap_id, op, flags))
+ return "OK", [b""]
+
+ def logout(self):
+ return "BYE", [b""]
+
+ fake = FakeIMAP()
+ monkeypatch.setattr("nanobot.channels.email.imaplib.IMAP4_SSL", lambda _h, _p: fake)
+
+ channel = EmailChannel(_make_config(), MessageBus())
+ items = channel.fetch_messages_between_dates(
+ start_date=date(2026, 2, 6),
+ end_date=date(2026, 2, 7),
+ limit=10,
+ )
+
+ assert len(items) == 1
+ assert items[0]["subject"] == "Status"
+ # search(None, "SINCE", "06-Feb-2026", "BEFORE", "07-Feb-2026")
+ assert fake.search_args is not None
+ assert fake.search_args[1:] == ("SINCE", "06-Feb-2026", "BEFORE", "07-Feb-2026")
+ assert fake.store_calls == []
diff --git a/nanobot/tests/test_feishu_post_content.py b/nanobot/tests/test_feishu_post_content.py
new file mode 100644
index 0000000..7b1cb9d
--- /dev/null
+++ b/nanobot/tests/test_feishu_post_content.py
@@ -0,0 +1,65 @@
+from nanobot.channels.feishu import FeishuChannel, _extract_post_content
+
+
+def test_extract_post_content_supports_post_wrapper_shape() -> None:
+ payload = {
+ "post": {
+ "zh_cn": {
+ "title": "日报",
+ "content": [
+ [
+ {"tag": "text", "text": "完成"},
+ {"tag": "img", "image_key": "img_1"},
+ ]
+ ],
+ }
+ }
+ }
+
+ text, image_keys = _extract_post_content(payload)
+
+ assert text == "日报 完成"
+ assert image_keys == ["img_1"]
+
+
+def test_extract_post_content_keeps_direct_shape_behavior() -> None:
+ payload = {
+ "title": "Daily",
+ "content": [
+ [
+ {"tag": "text", "text": "report"},
+ {"tag": "img", "image_key": "img_a"},
+ {"tag": "img", "image_key": "img_b"},
+ ]
+ ],
+ }
+
+ text, image_keys = _extract_post_content(payload)
+
+ assert text == "Daily report"
+ assert image_keys == ["img_a", "img_b"]
+
+
+def test_register_optional_event_keeps_builder_when_method_missing() -> None:
+ class Builder:
+ pass
+
+ builder = Builder()
+ same = FeishuChannel._register_optional_event(builder, "missing", object())
+ assert same is builder
+
+
+def test_register_optional_event_calls_supported_method() -> None:
+ called = []
+
+ class Builder:
+ def register_event(self, handler):
+ called.append(handler)
+ return self
+
+ builder = Builder()
+ handler = object()
+ same = FeishuChannel._register_optional_event(builder, "register_event", handler)
+
+ assert same is builder
+ assert called == [handler]
diff --git a/nanobot/tests/test_feishu_table_split.py b/nanobot/tests/test_feishu_table_split.py
new file mode 100644
index 0000000..af8fa16
--- /dev/null
+++ b/nanobot/tests/test_feishu_table_split.py
@@ -0,0 +1,104 @@
+"""Tests for FeishuChannel._split_elements_by_table_limit.
+
+Feishu cards reject messages that contain more than one table element
+(API error 11310: card table number over limit). The helper splits a flat
+list of card elements into groups so that each group contains at most one
+table, allowing nanobot to send multiple cards instead of failing.
+"""
+
+from nanobot.channels.feishu import FeishuChannel
+
+
+def _md(text: str) -> dict:
+ return {"tag": "markdown", "content": text}
+
+
+def _table() -> dict:
+ return {
+ "tag": "table",
+ "columns": [{"tag": "column", "name": "c0", "display_name": "A", "width": "auto"}],
+ "rows": [{"c0": "v"}],
+ "page_size": 2,
+ }
+
+
+split = FeishuChannel._split_elements_by_table_limit
+
+
+def test_empty_list_returns_single_empty_group() -> None:
+ assert split([]) == [[]]
+
+
+def test_no_tables_returns_single_group() -> None:
+ els = [_md("hello"), _md("world")]
+ result = split(els)
+ assert result == [els]
+
+
+def test_single_table_stays_in_one_group() -> None:
+ els = [_md("intro"), _table(), _md("outro")]
+ result = split(els)
+ assert len(result) == 1
+ assert result[0] == els
+
+
+def test_two_tables_split_into_two_groups() -> None:
+ # Use different row values so the two tables are not equal
+ t1 = {
+ "tag": "table",
+ "columns": [{"tag": "column", "name": "c0", "display_name": "A", "width": "auto"}],
+ "rows": [{"c0": "table-one"}],
+ "page_size": 2,
+ }
+ t2 = {
+ "tag": "table",
+ "columns": [{"tag": "column", "name": "c0", "display_name": "B", "width": "auto"}],
+ "rows": [{"c0": "table-two"}],
+ "page_size": 2,
+ }
+ els = [_md("before"), t1, _md("between"), t2, _md("after")]
+ result = split(els)
+ assert len(result) == 2
+ # First group: text before table-1 + table-1
+ assert t1 in result[0]
+ assert t2 not in result[0]
+ # Second group: text between tables + table-2 + text after
+ assert t2 in result[1]
+ assert t1 not in result[1]
+
+
+def test_three_tables_split_into_three_groups() -> None:
+ tables = [
+ {"tag": "table", "columns": [], "rows": [{"c0": f"t{i}"}], "page_size": 1}
+ for i in range(3)
+ ]
+ els = tables[:]
+ result = split(els)
+ assert len(result) == 3
+ for i, group in enumerate(result):
+ assert tables[i] in group
+
+
+def test_leading_markdown_stays_with_first_table() -> None:
+ intro = _md("intro")
+ t = _table()
+ result = split([intro, t])
+ assert len(result) == 1
+ assert result[0] == [intro, t]
+
+
+def test_trailing_markdown_after_second_table() -> None:
+ t1, t2 = _table(), _table()
+ tail = _md("end")
+ result = split([t1, t2, tail])
+ assert len(result) == 2
+ assert result[1] == [t2, tail]
+
+
+def test_non_table_elements_before_first_table_kept_in_first_group() -> None:
+ head = _md("head")
+ t1, t2 = _table(), _table()
+ result = split([head, t1, t2])
+ # head + t1 in group 0; t2 in group 1
+ assert result[0] == [head, t1]
+ assert result[1] == [t2]
diff --git a/nanobot/tests/test_heartbeat_service.py b/nanobot/tests/test_heartbeat_service.py
new file mode 100644
index 0000000..c5478af
--- /dev/null
+++ b/nanobot/tests/test_heartbeat_service.py
@@ -0,0 +1,117 @@
+import asyncio
+
+import pytest
+
+from nanobot.heartbeat.service import HeartbeatService
+from nanobot.providers.base import LLMResponse, ToolCallRequest
+
+
+class DummyProvider:
+ def __init__(self, responses: list[LLMResponse]):
+ self._responses = list(responses)
+
+ async def chat(self, *args, **kwargs) -> LLMResponse:
+ if self._responses:
+ return self._responses.pop(0)
+ return LLMResponse(content="", tool_calls=[])
+
+
+@pytest.mark.asyncio
+async def test_start_is_idempotent(tmp_path) -> None:
+ provider = DummyProvider([])
+
+ service = HeartbeatService(
+ workspace=tmp_path,
+ provider=provider,
+ model="openai/gpt-4o-mini",
+ interval_s=9999,
+ enabled=True,
+ )
+
+ await service.start()
+ first_task = service._task
+ await service.start()
+
+ assert service._task is first_task
+
+ service.stop()
+ await asyncio.sleep(0)
+
+
+@pytest.mark.asyncio
+async def test_decide_returns_skip_when_no_tool_call(tmp_path) -> None:
+ provider = DummyProvider([LLMResponse(content="no tool call", tool_calls=[])])
+ service = HeartbeatService(
+ workspace=tmp_path,
+ provider=provider,
+ model="openai/gpt-4o-mini",
+ )
+
+ action, tasks = await service._decide("heartbeat content")
+ assert action == "skip"
+ assert tasks == ""
+
+
+@pytest.mark.asyncio
+async def test_trigger_now_executes_when_decision_is_run(tmp_path) -> None:
+ (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
+
+ provider = DummyProvider([
+ LLMResponse(
+ content="",
+ tool_calls=[
+ ToolCallRequest(
+ id="hb_1",
+ name="heartbeat",
+ arguments={"action": "run", "tasks": "check open tasks"},
+ )
+ ],
+ )
+ ])
+
+ called_with: list[str] = []
+
+ async def _on_execute(tasks: str) -> str:
+ called_with.append(tasks)
+ return "done"
+
+ service = HeartbeatService(
+ workspace=tmp_path,
+ provider=provider,
+ model="openai/gpt-4o-mini",
+ on_execute=_on_execute,
+ )
+
+ result = await service.trigger_now()
+ assert result == "done"
+ assert called_with == ["check open tasks"]
+
+
+@pytest.mark.asyncio
+async def test_trigger_now_returns_none_when_decision_is_skip(tmp_path) -> None:
+ (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
+
+ provider = DummyProvider([
+ LLMResponse(
+ content="",
+ tool_calls=[
+ ToolCallRequest(
+ id="hb_1",
+ name="heartbeat",
+ arguments={"action": "skip"},
+ )
+ ],
+ )
+ ])
+
+ async def _on_execute(tasks: str) -> str:
+ return tasks
+
+ service = HeartbeatService(
+ workspace=tmp_path,
+ provider=provider,
+ model="openai/gpt-4o-mini",
+ on_execute=_on_execute,
+ )
+
+ assert await service.trigger_now() is None
diff --git a/nanobot/tests/test_loop_save_turn.py b/nanobot/tests/test_loop_save_turn.py
new file mode 100644
index 0000000..aec6d1a
--- /dev/null
+++ b/nanobot/tests/test_loop_save_turn.py
@@ -0,0 +1,41 @@
+from nanobot.agent.context import ContextBuilder
+from nanobot.agent.loop import AgentLoop
+from nanobot.session.manager import Session
+
+
+def _mk_loop() -> AgentLoop:
+ loop = AgentLoop.__new__(AgentLoop)
+ loop._TOOL_RESULT_MAX_CHARS = 500
+ return loop
+
+
+def test_save_turn_skips_multimodal_user_when_only_runtime_context() -> None:
+ loop = _mk_loop()
+ session = Session(key="test:runtime-only")
+ runtime = ContextBuilder._RUNTIME_CONTEXT_TAG + "\nCurrent Time: now (UTC)"
+
+ loop._save_turn(
+ session,
+ [{"role": "user", "content": [{"type": "text", "text": runtime}]}],
+ skip=0,
+ )
+ assert session.messages == []
+
+
+def test_save_turn_keeps_image_placeholder_after_runtime_strip() -> None:
+ loop = _mk_loop()
+ session = Session(key="test:image")
+ runtime = ContextBuilder._RUNTIME_CONTEXT_TAG + "\nCurrent Time: now (UTC)"
+
+ loop._save_turn(
+ session,
+ [{
+ "role": "user",
+ "content": [
+ {"type": "text", "text": runtime},
+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,abc"}},
+ ],
+ }],
+ skip=0,
+ )
+ assert session.messages[0]["content"] == [{"type": "text", "text": "[image]"}]
diff --git a/nanobot/tests/test_matrix_channel.py b/nanobot/tests/test_matrix_channel.py
new file mode 100644
index 0000000..c25b95a
--- /dev/null
+++ b/nanobot/tests/test_matrix_channel.py
@@ -0,0 +1,1318 @@
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import nanobot.channels.matrix as matrix_module
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.matrix import (
+ MATRIX_HTML_FORMAT,
+ TYPING_NOTICE_TIMEOUT_MS,
+ MatrixChannel,
+)
+from nanobot.config.schema import MatrixConfig
+
+_ROOM_SEND_UNSET = object()
+
+
+class _DummyTask:
+ def __init__(self) -> None:
+ self.cancelled = False
+
+ def cancel(self) -> None:
+ self.cancelled = True
+
+ def __await__(self):
+ async def _done():
+ return None
+
+ return _done().__await__()
+
+
+class _FakeAsyncClient:
+ def __init__(self, homeserver, user, store_path, config) -> None:
+ self.homeserver = homeserver
+ self.user = user
+ self.store_path = store_path
+ self.config = config
+ self.user_id: str | None = None
+ self.access_token: str | None = None
+ self.device_id: str | None = None
+ self.load_store_called = False
+ self.stop_sync_forever_called = False
+ self.join_calls: list[str] = []
+ self.callbacks: list[tuple[object, object]] = []
+ self.response_callbacks: list[tuple[object, object]] = []
+ self.rooms: dict[str, object] = {}
+ self.room_send_calls: list[dict[str, object]] = []
+ self.typing_calls: list[tuple[str, bool, int]] = []
+ self.download_calls: list[dict[str, object]] = []
+ self.upload_calls: list[dict[str, object]] = []
+ self.download_response: object | None = None
+ self.download_bytes: bytes = b"media"
+ self.download_content_type: str = "application/octet-stream"
+ self.download_filename: str | None = None
+ self.upload_response: object | None = None
+ self.content_repository_config_response: object = SimpleNamespace(upload_size=None)
+ self.raise_on_send = False
+ self.raise_on_typing = False
+ self.raise_on_upload = False
+
+ def add_event_callback(self, callback, event_type) -> None:
+ self.callbacks.append((callback, event_type))
+
+ def add_response_callback(self, callback, response_type) -> None:
+ self.response_callbacks.append((callback, response_type))
+
+ def load_store(self) -> None:
+ self.load_store_called = True
+
+ def stop_sync_forever(self) -> None:
+ self.stop_sync_forever_called = True
+
+ async def join(self, room_id: str) -> None:
+ self.join_calls.append(room_id)
+
+ async def room_send(
+ self,
+ room_id: str,
+ message_type: str,
+ content: dict[str, object],
+ ignore_unverified_devices: object = _ROOM_SEND_UNSET,
+ ) -> None:
+ call: dict[str, object] = {
+ "room_id": room_id,
+ "message_type": message_type,
+ "content": content,
+ }
+ if ignore_unverified_devices is not _ROOM_SEND_UNSET:
+ call["ignore_unverified_devices"] = ignore_unverified_devices
+ self.room_send_calls.append(call)
+ if self.raise_on_send:
+ raise RuntimeError("send failed")
+
+ async def room_typing(
+ self,
+ room_id: str,
+ typing_state: bool = True,
+ timeout: int = 30_000,
+ ) -> None:
+ self.typing_calls.append((room_id, typing_state, timeout))
+ if self.raise_on_typing:
+ raise RuntimeError("typing failed")
+
+ async def download(self, **kwargs):
+ self.download_calls.append(kwargs)
+ if self.download_response is not None:
+ return self.download_response
+ return matrix_module.MemoryDownloadResponse(
+ body=self.download_bytes,
+ content_type=self.download_content_type,
+ filename=self.download_filename,
+ )
+
+ async def upload(
+ self,
+ data_provider,
+ content_type: str | None = None,
+ filename: str | None = None,
+ filesize: int | None = None,
+ encrypt: bool = False,
+ ):
+ if self.raise_on_upload:
+ raise RuntimeError("upload failed")
+ if isinstance(data_provider, (bytes, bytearray)):
+ raise TypeError(
+ f"data_provider type {type(data_provider)!r} is not of a usable type "
+ "(Callable, IOBase)"
+ )
+ self.upload_calls.append(
+ {
+ "data_provider": data_provider,
+ "content_type": content_type,
+ "filename": filename,
+ "filesize": filesize,
+ "encrypt": encrypt,
+ }
+ )
+ if self.upload_response is not None:
+ return self.upload_response
+ if encrypt:
+ return (
+ SimpleNamespace(content_uri="mxc://example.org/uploaded"),
+ {
+ "v": "v2",
+ "iv": "iv",
+ "hashes": {"sha256": "hash"},
+ "key": {"alg": "A256CTR", "k": "key"},
+ },
+ )
+ return SimpleNamespace(content_uri="mxc://example.org/uploaded"), None
+
+ async def content_repository_config(self):
+ return self.content_repository_config_response
+
+ async def close(self) -> None:
+ return None
+
+
+def _make_config(**kwargs) -> MatrixConfig:
+ kwargs.setdefault("allow_from", ["*"])
+ return MatrixConfig(
+ enabled=True,
+ homeserver="https://matrix.org",
+ access_token="token",
+ user_id="@bot:matrix.org",
+ **kwargs,
+ )
+
+
+@pytest.mark.asyncio
+async def test_start_skips_load_store_when_device_id_missing(
+ monkeypatch, tmp_path
+) -> None:
+ clients: list[_FakeAsyncClient] = []
+
+ def _fake_client(*args, **kwargs) -> _FakeAsyncClient:
+ client = _FakeAsyncClient(*args, **kwargs)
+ clients.append(client)
+ return client
+
+ def _fake_create_task(coro):
+ coro.close()
+ return _DummyTask()
+
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+ monkeypatch.setattr(
+ "nanobot.channels.matrix.AsyncClientConfig",
+ lambda **kwargs: SimpleNamespace(**kwargs),
+ )
+ monkeypatch.setattr("nanobot.channels.matrix.AsyncClient", _fake_client)
+ monkeypatch.setattr(
+ "nanobot.channels.matrix.asyncio.create_task", _fake_create_task
+ )
+
+ channel = MatrixChannel(_make_config(device_id=""), MessageBus())
+ await channel.start()
+
+ assert len(clients) == 1
+ assert clients[0].config.encryption_enabled is True
+ assert clients[0].load_store_called is False
+ assert len(clients[0].callbacks) == 3
+ assert len(clients[0].response_callbacks) == 3
+
+ await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_register_event_callbacks_uses_media_base_filter() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ channel._register_event_callbacks()
+
+ assert len(client.callbacks) == 3
+ assert client.callbacks[1][0] == channel._on_media_message
+ assert client.callbacks[1][1] == matrix_module.MATRIX_MEDIA_EVENT_FILTER
+
+
+def test_media_event_filter_does_not_match_text_events() -> None:
+ assert not issubclass(matrix_module.RoomMessageText, matrix_module.MATRIX_MEDIA_EVENT_FILTER)
+
+
+@pytest.mark.asyncio
+async def test_start_disables_e2ee_when_configured(
+ monkeypatch, tmp_path
+) -> None:
+ clients: list[_FakeAsyncClient] = []
+
+ def _fake_client(*args, **kwargs) -> _FakeAsyncClient:
+ client = _FakeAsyncClient(*args, **kwargs)
+ clients.append(client)
+ return client
+
+ def _fake_create_task(coro):
+ coro.close()
+ return _DummyTask()
+
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+ monkeypatch.setattr(
+ "nanobot.channels.matrix.AsyncClientConfig",
+ lambda **kwargs: SimpleNamespace(**kwargs),
+ )
+ monkeypatch.setattr("nanobot.channels.matrix.AsyncClient", _fake_client)
+ monkeypatch.setattr(
+ "nanobot.channels.matrix.asyncio.create_task", _fake_create_task
+ )
+
+ channel = MatrixChannel(_make_config(device_id="", e2ee_enabled=False), MessageBus())
+ await channel.start()
+
+ assert len(clients) == 1
+ assert clients[0].config.encryption_enabled is False
+
+ await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_stop_stops_sync_forever_before_close(monkeypatch) -> None:
+ channel = MatrixChannel(_make_config(device_id="DEVICE"), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ task = _DummyTask()
+
+ channel.client = client
+ channel._sync_task = task
+ channel._running = True
+
+ await channel.stop()
+
+ assert channel._running is False
+ assert client.stop_sync_forever_called is True
+ assert task.cancelled is False
+
+
+@pytest.mark.asyncio
+async def test_room_invite_ignores_when_allow_list_is_empty() -> None:
+ channel = MatrixChannel(_make_config(allow_from=[]), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ room = SimpleNamespace(room_id="!room:matrix.org")
+ event = SimpleNamespace(sender="@alice:matrix.org")
+
+ await channel._on_room_invite(room, event)
+
+ assert client.join_calls == []
+
+
+@pytest.mark.asyncio
+async def test_room_invite_joins_when_sender_allowed() -> None:
+ channel = MatrixChannel(_make_config(allow_from=["@alice:matrix.org"]), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ room = SimpleNamespace(room_id="!room:matrix.org")
+ event = SimpleNamespace(sender="@alice:matrix.org")
+
+ await channel._on_room_invite(room, event)
+
+ assert client.join_calls == ["!room:matrix.org"]
+
+@pytest.mark.asyncio
+async def test_room_invite_respects_allow_list_when_configured() -> None:
+ channel = MatrixChannel(_make_config(allow_from=["@bob:matrix.org"]), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ room = SimpleNamespace(room_id="!room:matrix.org")
+ event = SimpleNamespace(sender="@alice:matrix.org")
+
+ await channel._on_room_invite(room, event)
+
+ assert client.join_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_sets_typing_for_allowed_sender() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+ event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={})
+
+ await channel._on_message(room, event)
+
+ assert handled == ["@alice:matrix.org"]
+ assert client.typing_calls == [
+ ("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS),
+ ]
+
+
+@pytest.mark.asyncio
+async def test_typing_keepalive_refreshes_periodically(monkeypatch) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+ channel._running = True
+
+ monkeypatch.setattr(matrix_module, "TYPING_KEEPALIVE_INTERVAL_MS", 10)
+
+ await channel._start_typing_keepalive("!room:matrix.org")
+ await asyncio.sleep(0.03)
+ await channel._stop_typing_keepalive("!room:matrix.org", clear_typing=True)
+
+ true_updates = [call for call in client.typing_calls if call[1] is True]
+ assert len(true_updates) >= 2
+ assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_on_message_skips_typing_for_self_message() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+ event = SimpleNamespace(sender="@bot:matrix.org", body="Hello", source={})
+
+ await channel._on_message(room, event)
+
+ assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_skips_typing_for_denied_sender() -> None:
+ channel = MatrixChannel(_make_config(allow_from=["@bob:matrix.org"]), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+ event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={})
+
+ await channel._on_message(room, event)
+
+ assert handled == []
+ assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_requires_mx_mentions() -> None:
+ channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+ event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+
+ await channel._on_message(room, event)
+
+ assert handled == []
+ assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_accepts_bot_user_mentions() -> None:
+ channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="Hello",
+ source={"content": {"m.mentions": {"user_ids": ["@bot:matrix.org"]}}},
+ )
+
+ await channel._on_message(room, event)
+
+ assert handled == ["@alice:matrix.org"]
+ assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_allows_direct_room_without_mentions() -> None:
+ channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!dm:matrix.org", display_name="DM", member_count=2)
+ event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+
+ await channel._on_message(room, event)
+
+ assert handled == ["@alice:matrix.org"]
+ assert client.typing_calls == [("!dm:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_allowlist_policy_requires_room_id() -> None:
+ channel = MatrixChannel(
+ _make_config(group_policy="allowlist", group_allow_from=["!allowed:matrix.org"]),
+ MessageBus(),
+ )
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["chat_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ denied_room = SimpleNamespace(room_id="!denied:matrix.org", display_name="Denied", member_count=3)
+ event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+ await channel._on_message(denied_room, event)
+
+ allowed_room = SimpleNamespace(
+ room_id="!allowed:matrix.org",
+ display_name="Allowed",
+ member_count=3,
+ )
+ await channel._on_message(allowed_room, event)
+
+ assert handled == ["!allowed:matrix.org"]
+ assert client.typing_calls == [("!allowed:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_room_mention_requires_opt_in() -> None:
+ channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[str] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs["sender_id"])
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+ room_mention_event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="Hello everyone",
+ source={"content": {"m.mentions": {"room": True}}},
+ )
+
+ await channel._on_message(room, room_mention_event)
+ assert handled == []
+ assert client.typing_calls == []
+
+ channel.config.allow_room_mentions = True
+ await channel._on_message(room, room_mention_event)
+ assert handled == ["@alice:matrix.org"]
+ assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_sets_thread_metadata_when_threaded_event() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="Hello",
+ event_id="$reply1",
+ source={
+ "content": {
+ "m.relates_to": {
+ "rel_type": "m.thread",
+ "event_id": "$root1",
+ }
+ }
+ },
+ )
+
+ await channel._on_message(room, event)
+
+ assert len(handled) == 1
+ metadata = handled[0]["metadata"]
+ assert metadata["thread_root_event_id"] == "$root1"
+ assert metadata["thread_reply_to_event_id"] == "$reply1"
+ assert metadata["event_id"] == "$reply1"
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_downloads_attachment_and_sets_metadata(
+ monkeypatch, tmp_path
+) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.download_bytes = b"image"
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="photo.png",
+ url="mxc://example.org/mediaid",
+ event_id="$event1",
+ source={
+ "content": {
+ "msgtype": "m.image",
+ "info": {"mimetype": "image/png", "size": 5},
+ }
+ },
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert len(client.download_calls) == 1
+ assert len(handled) == 1
+ assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+ media_paths = handled[0]["media"]
+ assert isinstance(media_paths, list) and len(media_paths) == 1
+ media_path = Path(media_paths[0])
+ assert media_path.is_file()
+ assert media_path.read_bytes() == b"image"
+
+ metadata = handled[0]["metadata"]
+ attachments = metadata["attachments"]
+ assert isinstance(attachments, list) and len(attachments) == 1
+ assert attachments[0]["type"] == "image"
+ assert attachments[0]["mxc_url"] == "mxc://example.org/mediaid"
+ assert attachments[0]["path"] == str(media_path)
+ assert "[attachment: " in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_sets_thread_metadata_when_threaded_event(
+ monkeypatch, tmp_path
+) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.download_bytes = b"image"
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="photo.png",
+ url="mxc://example.org/mediaid",
+ event_id="$event1",
+ source={
+ "content": {
+ "msgtype": "m.image",
+ "info": {"mimetype": "image/png", "size": 5},
+ "m.relates_to": {
+ "rel_type": "m.thread",
+ "event_id": "$root1",
+ },
+ }
+ },
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert len(handled) == 1
+ metadata = handled[0]["metadata"]
+ assert metadata["thread_root_event_id"] == "$root1"
+ assert metadata["thread_reply_to_event_id"] == "$event1"
+ assert metadata["event_id"] == "$event1"
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_respects_declared_size_limit(
+ monkeypatch, tmp_path
+) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ channel = MatrixChannel(_make_config(max_media_bytes=3), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="large.bin",
+ url="mxc://example.org/large",
+ event_id="$event2",
+ source={"content": {"msgtype": "m.file", "info": {"size": 10}}},
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert client.download_calls == []
+ assert len(handled) == 1
+ assert handled[0]["media"] == []
+ assert handled[0]["metadata"]["attachments"] == []
+ assert "[attachment: large.bin - too large]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_uses_server_limit_when_smaller_than_local_limit(
+ monkeypatch, tmp_path
+) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ channel = MatrixChannel(_make_config(max_media_bytes=10), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.content_repository_config_response = SimpleNamespace(upload_size=3)
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="large.bin",
+ url="mxc://example.org/large",
+ event_id="$event2_server",
+ source={"content": {"msgtype": "m.file", "info": {"size": 5}}},
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert client.download_calls == []
+ assert len(handled) == 1
+ assert handled[0]["media"] == []
+ assert handled[0]["metadata"]["attachments"] == []
+ assert "[attachment: large.bin - too large]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_handles_download_error(monkeypatch, tmp_path) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.download_response = matrix_module.DownloadError("download failed")
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="photo.png",
+ url="mxc://example.org/mediaid",
+ event_id="$event3",
+ source={"content": {"msgtype": "m.image"}},
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert len(client.download_calls) == 1
+ assert len(handled) == 1
+ assert handled[0]["media"] == []
+ assert handled[0]["metadata"]["attachments"] == []
+ assert "[attachment: photo.png - download failed]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_decrypts_encrypted_media(monkeypatch, tmp_path) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+ monkeypatch.setattr(
+ matrix_module,
+ "decrypt_attachment",
+ lambda ciphertext, key, sha256, iv: b"plain",
+ )
+
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.download_bytes = b"cipher"
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="secret.txt",
+ url="mxc://example.org/encrypted",
+ event_id="$event4",
+ key={"k": "key"},
+ hashes={"sha256": "hash"},
+ iv="iv",
+ source={"content": {"msgtype": "m.file", "info": {"size": 6}}},
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert len(handled) == 1
+ media_path = Path(handled[0]["media"][0])
+ assert media_path.read_bytes() == b"plain"
+ attachment = handled[0]["metadata"]["attachments"][0]
+ assert attachment["encrypted"] is True
+ assert attachment["size_bytes"] == 5
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_handles_decrypt_error(monkeypatch, tmp_path) -> None:
+ monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+ def _raise(*args, **kwargs):
+ raise matrix_module.EncryptionError("boom")
+
+ monkeypatch.setattr(matrix_module, "decrypt_attachment", _raise)
+
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.download_bytes = b"cipher"
+ channel.client = client
+
+ handled: list[dict[str, object]] = []
+
+ async def _fake_handle_message(**kwargs) -> None:
+ handled.append(kwargs)
+
+ channel._handle_message = _fake_handle_message # type: ignore[method-assign]
+
+ room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+ event = SimpleNamespace(
+ sender="@alice:matrix.org",
+ body="secret.txt",
+ url="mxc://example.org/encrypted",
+ event_id="$event5",
+ key={"k": "key"},
+ hashes={"sha256": "hash"},
+ iv="iv",
+ source={"content": {"msgtype": "m.file"}},
+ )
+
+ await channel._on_media_message(room, event)
+
+ assert len(handled) == 1
+ assert handled[0]["media"] == []
+ assert handled[0]["metadata"]["attachments"] == []
+ assert "[attachment: secret.txt - download failed]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_send_clears_typing_after_send() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+ )
+
+ assert len(client.room_send_calls) == 1
+ assert client.room_send_calls[0]["content"] == {
+ "msgtype": "m.text",
+ "body": "Hi",
+ "m.mentions": {},
+ }
+ assert client.room_send_calls[0]["ignore_unverified_devices"] is True
+ assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_uploads_media_and_sends_file_event(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ file_path = tmp_path / "test.txt"
+ file_path.write_text("hello", encoding="utf-8")
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="Please review.",
+ media=[str(file_path)],
+ )
+ )
+
+ assert len(client.upload_calls) == 1
+ assert not isinstance(client.upload_calls[0]["data_provider"], (bytes, bytearray))
+ assert hasattr(client.upload_calls[0]["data_provider"], "read")
+ assert client.upload_calls[0]["filename"] == "test.txt"
+ assert client.upload_calls[0]["filesize"] == 5
+ assert len(client.room_send_calls) == 2
+ assert client.room_send_calls[0]["content"]["msgtype"] == "m.file"
+ assert client.room_send_calls[0]["content"]["url"] == "mxc://example.org/uploaded"
+ assert client.room_send_calls[1]["content"]["body"] == "Please review."
+
+
+@pytest.mark.asyncio
+async def test_send_adds_thread_relates_to_for_thread_metadata() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ metadata = {
+ "thread_root_event_id": "$root1",
+ "thread_reply_to_event_id": "$reply1",
+ }
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="Hi",
+ metadata=metadata,
+ )
+ )
+
+ content = client.room_send_calls[0]["content"]
+ assert content["m.relates_to"] == {
+ "rel_type": "m.thread",
+ "event_id": "$root1",
+ "m.in_reply_to": {"event_id": "$reply1"},
+ "is_falling_back": True,
+ }
+
+
+@pytest.mark.asyncio
+async def test_send_uses_encrypted_media_payload_in_encrypted_room(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(e2ee_enabled=True), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.rooms["!encrypted:matrix.org"] = SimpleNamespace(encrypted=True)
+ channel.client = client
+
+ file_path = tmp_path / "secret.txt"
+ file_path.write_text("topsecret", encoding="utf-8")
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!encrypted:matrix.org",
+ content="",
+ media=[str(file_path)],
+ )
+ )
+
+ assert len(client.upload_calls) == 1
+ assert client.upload_calls[0]["encrypt"] is True
+ assert len(client.room_send_calls) == 1
+ content = client.room_send_calls[0]["content"]
+ assert content["msgtype"] == "m.file"
+ assert "file" in content
+ assert "url" not in content
+ assert content["file"]["url"] == "mxc://example.org/uploaded"
+ assert content["file"]["hashes"]["sha256"] == "hash"
+
+
+@pytest.mark.asyncio
+async def test_send_does_not_parse_attachment_marker_without_media(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ missing_path = tmp_path / "missing.txt"
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content=f"[attachment: {missing_path}]",
+ )
+ )
+
+ assert client.upload_calls == []
+ assert len(client.room_send_calls) == 1
+ assert client.room_send_calls[0]["content"]["body"] == f"[attachment: {missing_path}]"
+
+
+@pytest.mark.asyncio
+async def test_send_passes_thread_relates_to_to_attachment_upload(monkeypatch) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+ channel._server_upload_limit_checked = True
+ channel._server_upload_limit_bytes = None
+
+ captured: dict[str, object] = {}
+
+ async def _fake_upload_and_send_attachment(
+ *,
+ room_id: str,
+ path: Path,
+ limit_bytes: int,
+ relates_to: dict[str, object] | None = None,
+ ) -> str | None:
+ captured["relates_to"] = relates_to
+ return None
+
+ monkeypatch.setattr(channel, "_upload_and_send_attachment", _fake_upload_and_send_attachment)
+
+ metadata = {
+ "thread_root_event_id": "$root1",
+ "thread_reply_to_event_id": "$reply1",
+ }
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="Hi",
+ media=["/tmp/fake.txt"],
+ metadata=metadata,
+ )
+ )
+
+ assert captured["relates_to"] == {
+ "rel_type": "m.thread",
+ "event_id": "$root1",
+ "m.in_reply_to": {"event_id": "$reply1"},
+ "is_falling_back": True,
+ }
+
+
+@pytest.mark.asyncio
+async def test_send_workspace_restriction_blocks_external_attachment(tmp_path) -> None:
+ workspace = tmp_path / "workspace"
+ workspace.mkdir()
+ file_path = tmp_path / "external.txt"
+ file_path.write_text("outside", encoding="utf-8")
+
+ channel = MatrixChannel(
+ _make_config(),
+ MessageBus(),
+ restrict_to_workspace=True,
+ workspace=workspace,
+ )
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="",
+ media=[str(file_path)],
+ )
+ )
+
+ assert client.upload_calls == []
+ assert len(client.room_send_calls) == 1
+ assert client.room_send_calls[0]["content"]["body"] == "[attachment: external.txt - upload failed]"
+
+
+@pytest.mark.asyncio
+async def test_send_handles_upload_exception_and_reports_failure(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.raise_on_upload = True
+ channel.client = client
+
+ file_path = tmp_path / "broken.txt"
+ file_path.write_text("hello", encoding="utf-8")
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="Please review.",
+ media=[str(file_path)],
+ )
+ )
+
+ assert len(client.upload_calls) == 0
+ assert len(client.room_send_calls) == 1
+ assert (
+ client.room_send_calls[0]["content"]["body"]
+ == "Please review.\n[attachment: broken.txt - upload failed]"
+ )
+
+
+@pytest.mark.asyncio
+async def test_send_uses_server_upload_limit_when_smaller_than_local_limit(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(max_media_bytes=10), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.content_repository_config_response = SimpleNamespace(upload_size=3)
+ channel.client = client
+
+ file_path = tmp_path / "tiny.txt"
+ file_path.write_text("hello", encoding="utf-8")
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="",
+ media=[str(file_path)],
+ )
+ )
+
+ assert client.upload_calls == []
+ assert len(client.room_send_calls) == 1
+ assert client.room_send_calls[0]["content"]["body"] == "[attachment: tiny.txt - too large]"
+
+
+@pytest.mark.asyncio
+async def test_send_blocks_all_outbound_media_when_limit_is_zero(tmp_path) -> None:
+ channel = MatrixChannel(_make_config(max_media_bytes=0), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ file_path = tmp_path / "empty.txt"
+ file_path.write_bytes(b"")
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="",
+ media=[str(file_path)],
+ )
+ )
+
+ assert client.upload_calls == []
+ assert len(client.room_send_calls) == 1
+ assert client.room_send_calls[0]["content"]["body"] == "[attachment: empty.txt - too large]"
+
+
+@pytest.mark.asyncio
+async def test_send_omits_ignore_unverified_devices_when_e2ee_disabled() -> None:
+ channel = MatrixChannel(_make_config(e2ee_enabled=False), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+ )
+
+ assert len(client.room_send_calls) == 1
+ assert "ignore_unverified_devices" not in client.room_send_calls[0]
+
+
+@pytest.mark.asyncio
+async def test_send_stops_typing_keepalive_task() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+ channel._running = True
+
+ await channel._start_typing_keepalive("!room:matrix.org")
+ assert "!room:matrix.org" in channel._typing_tasks
+
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+ )
+
+ assert "!room:matrix.org" not in channel._typing_tasks
+ assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_progress_keeps_typing_keepalive_running() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+ channel._running = True
+
+ await channel._start_typing_keepalive("!room:matrix.org")
+ assert "!room:matrix.org" in channel._typing_tasks
+
+ await channel.send(
+ OutboundMessage(
+ channel="matrix",
+ chat_id="!room:matrix.org",
+ content="working...",
+ metadata={"_progress": True, "_progress_kind": "reasoning"},
+ )
+ )
+
+ assert "!room:matrix.org" in channel._typing_tasks
+ assert client.typing_calls[-1] == ("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)
+
+ await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_send_clears_typing_when_send_fails() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ client.raise_on_send = True
+ channel.client = client
+
+ with pytest.raises(RuntimeError, match="send failed"):
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+ )
+
+ assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_adds_formatted_body_for_markdown() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ markdown_text = "# Headline\n\n- [x] done\n\n| A | B |\n| - | - |\n| 1 | 2 |"
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+ )
+
+ content = client.room_send_calls[0]["content"]
+ assert content["msgtype"] == "m.text"
+ assert content["body"] == markdown_text
+ assert content["m.mentions"] == {}
+ assert content["format"] == MATRIX_HTML_FORMAT
+ assert "Headline
" in str(content["formatted_body"])
+ assert "" in str(content["formatted_body"])
+ assert "[x] done " in str(content["formatted_body"])
+
+
+@pytest.mark.asyncio
+async def test_send_adds_formatted_body_for_inline_url_superscript_subscript() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ markdown_text = "Visit https://example.com and x^2^ plus H~2~O."
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+ )
+
+ content = client.room_send_calls[0]["content"]
+ assert content["msgtype"] == "m.text"
+ assert content["body"] == markdown_text
+ assert content["m.mentions"] == {}
+ assert content["format"] == MATRIX_HTML_FORMAT
+ assert '' in str(
+ content["formatted_body"]
+ )
+ assert "2" in str(content["formatted_body"])
+ assert "2" in str(content["formatted_body"])
+
+
+@pytest.mark.asyncio
+async def test_send_sanitizes_disallowed_link_scheme() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ markdown_text = "[click](javascript:alert(1))"
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+ )
+
+ formatted_body = str(client.room_send_calls[0]["content"]["formatted_body"])
+ assert "javascript:" not in formatted_body
+ assert "x '
+ cleaned_html = matrix_module.MATRIX_HTML_CLEANER.clean(dirty_html)
+
+ assert " None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ markdown_text = " "
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+ )
+
+ formatted_body = str(client.room_send_calls[0]["content"]["formatted_body"])
+ assert 'src="mxc://example.org/mediaid"' in formatted_body
+ assert 'src="https://example.com/a.png"' not in formatted_body
+
+
+@pytest.mark.asyncio
+async def test_send_falls_back_to_plaintext_when_markdown_render_fails(monkeypatch) -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ def _raise(text: str) -> str:
+ raise RuntimeError("boom")
+
+ monkeypatch.setattr(matrix_module, "MATRIX_MARKDOWN", _raise)
+ markdown_text = "# Headline"
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+ )
+
+ content = client.room_send_calls[0]["content"]
+ assert content == {"msgtype": "m.text", "body": markdown_text, "m.mentions": {}}
+
+
+@pytest.mark.asyncio
+async def test_send_keeps_plaintext_only_for_plain_text() -> None:
+ channel = MatrixChannel(_make_config(), MessageBus())
+ client = _FakeAsyncClient("", "", "", None)
+ channel.client = client
+
+ text = "just a normal sentence without markdown markers"
+ await channel.send(
+ OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=text)
+ )
+
+ assert client.room_send_calls[0]["content"] == {
+ "msgtype": "m.text",
+ "body": text,
+ "m.mentions": {},
+ }
diff --git a/nanobot/tests/test_mcp_tool.py b/nanobot/tests/test_mcp_tool.py
new file mode 100644
index 0000000..bf68425
--- /dev/null
+++ b/nanobot/tests/test_mcp_tool.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from types import ModuleType, SimpleNamespace
+
+import pytest
+
+from nanobot.agent.tools.mcp import MCPToolWrapper
+
+
+class _FakeTextContent:
+ def __init__(self, text: str) -> None:
+ self.text = text
+
+
+@pytest.fixture(autouse=True)
+def _fake_mcp_module(monkeypatch: pytest.MonkeyPatch) -> None:
+ mod = ModuleType("mcp")
+ mod.types = SimpleNamespace(TextContent=_FakeTextContent)
+ monkeypatch.setitem(sys.modules, "mcp", mod)
+
+
+def _make_wrapper(session: object, *, timeout: float = 0.1) -> MCPToolWrapper:
+ tool_def = SimpleNamespace(
+ name="demo",
+ description="demo tool",
+ inputSchema={"type": "object", "properties": {}},
+ )
+ return MCPToolWrapper(session, "test", tool_def, tool_timeout=timeout)
+
+
+@pytest.mark.asyncio
+async def test_execute_returns_text_blocks() -> None:
+ async def call_tool(_name: str, arguments: dict) -> object:
+ assert arguments == {"value": 1}
+ return SimpleNamespace(content=[_FakeTextContent("hello"), 42])
+
+ wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+ result = await wrapper.execute(value=1)
+
+ assert result == "hello\n42"
+
+
+@pytest.mark.asyncio
+async def test_execute_returns_timeout_message() -> None:
+ async def call_tool(_name: str, arguments: dict) -> object:
+ await asyncio.sleep(1)
+ return SimpleNamespace(content=[])
+
+ wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool), timeout=0.01)
+
+ result = await wrapper.execute()
+
+ assert result == "(MCP tool call timed out after 0.01s)"
+
+
+@pytest.mark.asyncio
+async def test_execute_handles_server_cancelled_error() -> None:
+ async def call_tool(_name: str, arguments: dict) -> object:
+ raise asyncio.CancelledError()
+
+ wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+ result = await wrapper.execute()
+
+ assert result == "(MCP tool call was cancelled)"
+
+
+@pytest.mark.asyncio
+async def test_execute_re_raises_external_cancellation() -> None:
+ started = asyncio.Event()
+
+ async def call_tool(_name: str, arguments: dict) -> object:
+ started.set()
+ await asyncio.sleep(60)
+ return SimpleNamespace(content=[])
+
+ wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool), timeout=10)
+ task = asyncio.create_task(wrapper.execute())
+ await started.wait()
+
+ task.cancel()
+
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
+
+@pytest.mark.asyncio
+async def test_execute_handles_generic_exception() -> None:
+ async def call_tool(_name: str, arguments: dict) -> object:
+ raise RuntimeError("boom")
+
+ wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+ result = await wrapper.execute()
+
+ assert result == "(MCP tool call failed: RuntimeError)"
diff --git a/nanobot/tests/test_memory_consolidation_types.py b/nanobot/tests/test_memory_consolidation_types.py
new file mode 100644
index 0000000..ff15584
--- /dev/null
+++ b/nanobot/tests/test_memory_consolidation_types.py
@@ -0,0 +1,222 @@
+"""Test MemoryStore.consolidate() handles non-string tool call arguments.
+
+Regression test for https://github.com/HKUDS/nanobot/issues/1042
+When memory consolidation receives dict values instead of strings from the LLM
+tool call response, it should serialize them to JSON instead of raising TypeError.
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.memory import MemoryStore
+from nanobot.providers.base import LLMResponse, ToolCallRequest
+
+
+def _make_session(message_count: int = 30, memory_window: int = 50):
+ """Create a mock session with messages."""
+ session = MagicMock()
+ session.messages = [
+ {"role": "user", "content": f"msg{i}", "timestamp": "2026-01-01 00:00"}
+ for i in range(message_count)
+ ]
+ session.last_consolidated = 0
+ return session
+
+
+def _make_tool_response(history_entry, memory_update):
+ """Create an LLMResponse with a save_memory tool call."""
+ return LLMResponse(
+ content=None,
+ tool_calls=[
+ ToolCallRequest(
+ id="call_1",
+ name="save_memory",
+ arguments={
+ "history_entry": history_entry,
+ "memory_update": memory_update,
+ },
+ )
+ ],
+ )
+
+
+class TestMemoryConsolidationTypeHandling:
+ """Test that consolidation handles various argument types correctly."""
+
+ @pytest.mark.asyncio
+ async def test_string_arguments_work(self, tmp_path: Path) -> None:
+ """Normal case: LLM returns string arguments."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+ provider.chat = AsyncMock(
+ return_value=_make_tool_response(
+ history_entry="[2026-01-01] User discussed testing.",
+ memory_update="# Memory\nUser likes testing.",
+ )
+ )
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is True
+ assert store.history_file.exists()
+ assert "[2026-01-01] User discussed testing." in store.history_file.read_text()
+ assert "User likes testing." in store.memory_file.read_text()
+
+ @pytest.mark.asyncio
+ async def test_dict_arguments_serialized_to_json(self, tmp_path: Path) -> None:
+ """Issue #1042: LLM returns dict instead of string — must not raise TypeError."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+ provider.chat = AsyncMock(
+ return_value=_make_tool_response(
+ history_entry={"timestamp": "2026-01-01", "summary": "User discussed testing."},
+ memory_update={"facts": ["User likes testing"], "topics": ["testing"]},
+ )
+ )
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is True
+ assert store.history_file.exists()
+ history_content = store.history_file.read_text()
+ parsed = json.loads(history_content.strip())
+ assert parsed["summary"] == "User discussed testing."
+
+ memory_content = store.memory_file.read_text()
+ parsed_mem = json.loads(memory_content)
+ assert "User likes testing" in parsed_mem["facts"]
+
+ @pytest.mark.asyncio
+ async def test_string_arguments_as_raw_json(self, tmp_path: Path) -> None:
+ """Some providers return arguments as a JSON string instead of parsed dict."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+
+ # Simulate arguments being a JSON string (not yet parsed)
+ response = LLMResponse(
+ content=None,
+ tool_calls=[
+ ToolCallRequest(
+ id="call_1",
+ name="save_memory",
+ arguments=json.dumps({
+ "history_entry": "[2026-01-01] User discussed testing.",
+ "memory_update": "# Memory\nUser likes testing.",
+ }),
+ )
+ ],
+ )
+ provider.chat = AsyncMock(return_value=response)
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is True
+ assert "User discussed testing." in store.history_file.read_text()
+
+ @pytest.mark.asyncio
+ async def test_no_tool_call_returns_false(self, tmp_path: Path) -> None:
+ """When LLM doesn't use the save_memory tool, return False."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+ provider.chat = AsyncMock(
+ return_value=LLMResponse(content="I summarized the conversation.", tool_calls=[])
+ )
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is False
+ assert not store.history_file.exists()
+
+ @pytest.mark.asyncio
+ async def test_skips_when_few_messages(self, tmp_path: Path) -> None:
+ """Consolidation should be a no-op when messages < keep_count."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+ session = _make_session(message_count=10)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is True
+ provider.chat.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_list_arguments_extracts_first_dict(self, tmp_path: Path) -> None:
+ """Some providers return arguments as a list - extract first element if it's a dict."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+
+ # Simulate arguments being a list containing a dict
+ response = LLMResponse(
+ content=None,
+ tool_calls=[
+ ToolCallRequest(
+ id="call_1",
+ name="save_memory",
+ arguments=[{
+ "history_entry": "[2026-01-01] User discussed testing.",
+ "memory_update": "# Memory\nUser likes testing.",
+ }],
+ )
+ ],
+ )
+ provider.chat = AsyncMock(return_value=response)
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is True
+ assert "User discussed testing." in store.history_file.read_text()
+ assert "User likes testing." in store.memory_file.read_text()
+
+ @pytest.mark.asyncio
+ async def test_list_arguments_empty_list_returns_false(self, tmp_path: Path) -> None:
+ """Empty list arguments should return False."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+
+ response = LLMResponse(
+ content=None,
+ tool_calls=[
+ ToolCallRequest(
+ id="call_1",
+ name="save_memory",
+ arguments=[],
+ )
+ ],
+ )
+ provider.chat = AsyncMock(return_value=response)
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_list_arguments_non_dict_content_returns_false(self, tmp_path: Path) -> None:
+ """List with non-dict content should return False."""
+ store = MemoryStore(tmp_path)
+ provider = AsyncMock()
+
+ response = LLMResponse(
+ content=None,
+ tool_calls=[
+ ToolCallRequest(
+ id="call_1",
+ name="save_memory",
+ arguments=["string", "content"],
+ )
+ ],
+ )
+ provider.chat = AsyncMock(return_value=response)
+ session = _make_session(message_count=60)
+
+ result = await store.consolidate(session, provider, "test-model", memory_window=50)
+
+ assert result is False
diff --git a/nanobot/tests/test_message_tool.py b/nanobot/tests/test_message_tool.py
new file mode 100644
index 0000000..dc8e11d
--- /dev/null
+++ b/nanobot/tests/test_message_tool.py
@@ -0,0 +1,10 @@
+import pytest
+
+from nanobot.agent.tools.message import MessageTool
+
+
+@pytest.mark.asyncio
+async def test_message_tool_returns_error_when_no_target_context() -> None:
+ tool = MessageTool()
+ result = await tool.execute(content="test")
+ assert result == "Error: No target channel/chat specified"
diff --git a/nanobot/tests/test_message_tool_suppress.py b/nanobot/tests/test_message_tool_suppress.py
new file mode 100644
index 0000000..63b0fd1
--- /dev/null
+++ b/nanobot/tests/test_message_tool_suppress.py
@@ -0,0 +1,132 @@
+"""Test message tool suppress logic for final replies."""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop
+from nanobot.agent.tools.message import MessageTool
+from nanobot.bus.events import InboundMessage, OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import LLMResponse, ToolCallRequest
+
+
+def _make_loop(tmp_path: Path) -> AgentLoop:
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ return AgentLoop(bus=bus, provider=provider, workspace=tmp_path, model="test-model", memory_window=10)
+
+
+class TestMessageToolSuppressLogic:
+ """Final reply suppressed only when message tool sends to the same target."""
+
+ @pytest.mark.asyncio
+ async def test_suppress_when_sent_to_same_target(self, tmp_path: Path) -> None:
+ loop = _make_loop(tmp_path)
+ tool_call = ToolCallRequest(
+ id="call1", name="message",
+ arguments={"content": "Hello", "channel": "feishu", "chat_id": "chat123"},
+ )
+ calls = iter([
+ LLMResponse(content="", tool_calls=[tool_call]),
+ LLMResponse(content="Done", tool_calls=[]),
+ ])
+ loop.provider.chat = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ sent: list[OutboundMessage] = []
+ mt = loop.tools.get("message")
+ if isinstance(mt, MessageTool):
+ mt.set_send_callback(AsyncMock(side_effect=lambda m: sent.append(m)))
+
+ msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Send")
+ result = await loop._process_message(msg)
+
+ assert len(sent) == 1
+ assert result is None # suppressed
+
+ @pytest.mark.asyncio
+ async def test_not_suppress_when_sent_to_different_target(self, tmp_path: Path) -> None:
+ loop = _make_loop(tmp_path)
+ tool_call = ToolCallRequest(
+ id="call1", name="message",
+ arguments={"content": "Email content", "channel": "email", "chat_id": "user@example.com"},
+ )
+ calls = iter([
+ LLMResponse(content="", tool_calls=[tool_call]),
+ LLMResponse(content="I've sent the email.", tool_calls=[]),
+ ])
+ loop.provider.chat = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ sent: list[OutboundMessage] = []
+ mt = loop.tools.get("message")
+ if isinstance(mt, MessageTool):
+ mt.set_send_callback(AsyncMock(side_effect=lambda m: sent.append(m)))
+
+ msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Send email")
+ result = await loop._process_message(msg)
+
+ assert len(sent) == 1
+ assert sent[0].channel == "email"
+ assert result is not None # not suppressed
+ assert result.channel == "feishu"
+
+ @pytest.mark.asyncio
+ async def test_not_suppress_when_no_message_tool_used(self, tmp_path: Path) -> None:
+ loop = _make_loop(tmp_path)
+ loop.provider.chat = AsyncMock(return_value=LLMResponse(content="Hello!", tool_calls=[]))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+
+ msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Hi")
+ result = await loop._process_message(msg)
+
+ assert result is not None
+ assert "Hello" in result.content
+
+ async def test_progress_hides_internal_reasoning(self, tmp_path: Path) -> None:
+ loop = _make_loop(tmp_path)
+ tool_call = ToolCallRequest(id="call1", name="read_file", arguments={"path": "foo.txt"})
+ calls = iter([
+ LLMResponse(
+ content="Visiblehidden ",
+ tool_calls=[tool_call],
+ reasoning_content="secret reasoning",
+ thinking_blocks=[{"signature": "sig", "thought": "secret thought"}],
+ ),
+ LLMResponse(content="Done", tool_calls=[]),
+ ])
+ loop.provider.chat = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+ loop.tools.get_definitions = MagicMock(return_value=[])
+ loop.tools.execute = AsyncMock(return_value="ok")
+
+ progress: list[tuple[str, bool]] = []
+
+ async def on_progress(content: str, *, tool_hint: bool = False) -> None:
+ progress.append((content, tool_hint))
+
+ final_content, _, _ = await loop._run_agent_loop([], on_progress=on_progress)
+
+ assert final_content == "Done"
+ assert progress == [
+ ("Visible", False),
+ ('read_file("foo.txt")', True),
+ ]
+
+
+class TestMessageToolTurnTracking:
+
+ def test_sent_in_turn_tracks_same_target(self) -> None:
+ tool = MessageTool()
+ tool.set_context("feishu", "chat1")
+ assert not tool._sent_in_turn
+ tool._sent_in_turn = True
+ assert tool._sent_in_turn
+
+ def test_start_turn_resets(self) -> None:
+ tool = MessageTool()
+ tool._sent_in_turn = True
+ tool.start_turn()
+ assert not tool._sent_in_turn
diff --git a/nanobot/tests/test_qq_channel.py b/nanobot/tests/test_qq_channel.py
new file mode 100644
index 0000000..90b4e60
--- /dev/null
+++ b/nanobot/tests/test_qq_channel.py
@@ -0,0 +1,66 @@
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.qq import QQChannel
+from nanobot.config.schema import QQConfig
+
+
+class _FakeApi:
+ def __init__(self) -> None:
+ self.c2c_calls: list[dict] = []
+ self.group_calls: list[dict] = []
+
+ async def post_c2c_message(self, **kwargs) -> None:
+ self.c2c_calls.append(kwargs)
+
+ async def post_group_message(self, **kwargs) -> None:
+ self.group_calls.append(kwargs)
+
+
+class _FakeClient:
+ def __init__(self) -> None:
+ self.api = _FakeApi()
+
+
+@pytest.mark.asyncio
+async def test_on_group_message_routes_to_group_chat_id() -> None:
+ channel = QQChannel(QQConfig(app_id="app", secret="secret", allow_from=["user1"]), MessageBus())
+
+ data = SimpleNamespace(
+ id="msg1",
+ content="hello",
+ group_openid="group123",
+ author=SimpleNamespace(member_openid="user1"),
+ )
+
+ await channel._on_message(data, is_group=True)
+
+ msg = await channel.bus.consume_inbound()
+ assert msg.sender_id == "user1"
+ assert msg.chat_id == "group123"
+
+
+@pytest.mark.asyncio
+async def test_send_group_message_uses_group_api_with_msg_seq() -> None:
+ channel = QQChannel(QQConfig(app_id="app", secret="secret", allow_from=["*"]), MessageBus())
+ channel._client = _FakeClient()
+ channel._chat_type_cache["group123"] = "group"
+
+ await channel.send(
+ OutboundMessage(
+ channel="qq",
+ chat_id="group123",
+ content="hello",
+ metadata={"message_id": "msg1"},
+ )
+ )
+
+ assert len(channel._client.api.group_calls) == 1
+ call = channel._client.api.group_calls[0]
+ assert call["group_openid"] == "group123"
+ assert call["msg_id"] == "msg1"
+ assert call["msg_seq"] == 2
+ assert not channel._client.api.c2c_calls
diff --git a/nanobot/tests/test_task_cancel.py b/nanobot/tests/test_task_cancel.py
new file mode 100644
index 0000000..27a2d73
--- /dev/null
+++ b/nanobot/tests/test_task_cancel.py
@@ -0,0 +1,167 @@
+"""Tests for /stop task cancellation."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+def _make_loop():
+ """Create a minimal AgentLoop with mocked dependencies."""
+ from nanobot.agent.loop import AgentLoop
+ from nanobot.bus.queue import MessageBus
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ workspace = MagicMock()
+ workspace.__truediv__ = MagicMock(return_value=MagicMock())
+
+ with patch("nanobot.agent.loop.ContextBuilder"), \
+ patch("nanobot.agent.loop.SessionManager"), \
+ patch("nanobot.agent.loop.SubagentManager") as MockSubMgr:
+ MockSubMgr.return_value.cancel_by_session = AsyncMock(return_value=0)
+ loop = AgentLoop(bus=bus, provider=provider, workspace=workspace)
+ return loop, bus
+
+
+class TestHandleStop:
+ @pytest.mark.asyncio
+ async def test_stop_no_active_task(self):
+ from nanobot.bus.events import InboundMessage
+
+ loop, bus = _make_loop()
+ msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+ await loop._handle_stop(msg)
+ out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+ assert "No active task" in out.content
+
+ @pytest.mark.asyncio
+ async def test_stop_cancels_active_task(self):
+ from nanobot.bus.events import InboundMessage
+
+ loop, bus = _make_loop()
+ cancelled = asyncio.Event()
+
+ async def slow_task():
+ try:
+ await asyncio.sleep(60)
+ except asyncio.CancelledError:
+ cancelled.set()
+ raise
+
+ task = asyncio.create_task(slow_task())
+ await asyncio.sleep(0)
+ loop._active_tasks["test:c1"] = [task]
+
+ msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+ await loop._handle_stop(msg)
+
+ assert cancelled.is_set()
+ out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+ assert "stopped" in out.content.lower()
+
+ @pytest.mark.asyncio
+ async def test_stop_cancels_multiple_tasks(self):
+ from nanobot.bus.events import InboundMessage
+
+ loop, bus = _make_loop()
+ events = [asyncio.Event(), asyncio.Event()]
+
+ async def slow(idx):
+ try:
+ await asyncio.sleep(60)
+ except asyncio.CancelledError:
+ events[idx].set()
+ raise
+
+ tasks = [asyncio.create_task(slow(i)) for i in range(2)]
+ await asyncio.sleep(0)
+ loop._active_tasks["test:c1"] = tasks
+
+ msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+ await loop._handle_stop(msg)
+
+ assert all(e.is_set() for e in events)
+ out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+ assert "2 task" in out.content
+
+
+class TestDispatch:
+ @pytest.mark.asyncio
+ async def test_dispatch_processes_and_publishes(self):
+ from nanobot.bus.events import InboundMessage, OutboundMessage
+
+ loop, bus = _make_loop()
+ msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="hello")
+ loop._process_message = AsyncMock(
+ return_value=OutboundMessage(channel="test", chat_id="c1", content="hi")
+ )
+ await loop._dispatch(msg)
+ out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+ assert out.content == "hi"
+
+ @pytest.mark.asyncio
+ async def test_processing_lock_serializes(self):
+ from nanobot.bus.events import InboundMessage, OutboundMessage
+
+ loop, bus = _make_loop()
+ order = []
+
+ async def mock_process(m, **kwargs):
+ order.append(f"start-{m.content}")
+ await asyncio.sleep(0.05)
+ order.append(f"end-{m.content}")
+ return OutboundMessage(channel="test", chat_id="c1", content=m.content)
+
+ loop._process_message = mock_process
+ msg1 = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="a")
+ msg2 = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="b")
+
+ t1 = asyncio.create_task(loop._dispatch(msg1))
+ t2 = asyncio.create_task(loop._dispatch(msg2))
+ await asyncio.gather(t1, t2)
+ assert order == ["start-a", "end-a", "start-b", "end-b"]
+
+
+class TestSubagentCancellation:
+ @pytest.mark.asyncio
+ async def test_cancel_by_session(self):
+ from nanobot.agent.subagent import SubagentManager
+ from nanobot.bus.queue import MessageBus
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ mgr = SubagentManager(provider=provider, workspace=MagicMock(), bus=bus)
+
+ cancelled = asyncio.Event()
+
+ async def slow():
+ try:
+ await asyncio.sleep(60)
+ except asyncio.CancelledError:
+ cancelled.set()
+ raise
+
+ task = asyncio.create_task(slow())
+ await asyncio.sleep(0)
+ mgr._running_tasks["sub-1"] = task
+ mgr._session_tasks["test:c1"] = {"sub-1"}
+
+ count = await mgr.cancel_by_session("test:c1")
+ assert count == 1
+ assert cancelled.is_set()
+
+ @pytest.mark.asyncio
+ async def test_cancel_by_session_no_tasks(self):
+ from nanobot.agent.subagent import SubagentManager
+ from nanobot.bus.queue import MessageBus
+
+ bus = MessageBus()
+ provider = MagicMock()
+ provider.get_default_model.return_value = "test-model"
+ mgr = SubagentManager(provider=provider, workspace=MagicMock(), bus=bus)
+ assert await mgr.cancel_by_session("nonexistent") == 0
diff --git a/nanobot/tests/test_telegram_channel.py b/nanobot/tests/test_telegram_channel.py
new file mode 100644
index 0000000..88c3f54
--- /dev/null
+++ b/nanobot/tests/test_telegram_channel.py
@@ -0,0 +1,184 @@
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.telegram import TelegramChannel
+from nanobot.config.schema import TelegramConfig
+
+
+class _FakeHTTPXRequest:
+ instances: list["_FakeHTTPXRequest"] = []
+
+ def __init__(self, **kwargs) -> None:
+ self.kwargs = kwargs
+ self.__class__.instances.append(self)
+
+
+class _FakeUpdater:
+ def __init__(self, on_start_polling) -> None:
+ self._on_start_polling = on_start_polling
+
+ async def start_polling(self, **kwargs) -> None:
+ self._on_start_polling()
+
+
+class _FakeBot:
+ def __init__(self) -> None:
+ self.sent_messages: list[dict] = []
+
+ async def get_me(self):
+ return SimpleNamespace(username="nanobot_test")
+
+ async def set_my_commands(self, commands) -> None:
+ self.commands = commands
+
+ async def send_message(self, **kwargs) -> None:
+ self.sent_messages.append(kwargs)
+
+
+class _FakeApp:
+ def __init__(self, on_start_polling) -> None:
+ self.bot = _FakeBot()
+ self.updater = _FakeUpdater(on_start_polling)
+ self.handlers = []
+ self.error_handlers = []
+
+ def add_error_handler(self, handler) -> None:
+ self.error_handlers.append(handler)
+
+ def add_handler(self, handler) -> None:
+ self.handlers.append(handler)
+
+ async def initialize(self) -> None:
+ pass
+
+ async def start(self) -> None:
+ pass
+
+
+class _FakeBuilder:
+ def __init__(self, app: _FakeApp) -> None:
+ self.app = app
+ self.token_value = None
+ self.request_value = None
+ self.get_updates_request_value = None
+
+ def token(self, token: str):
+ self.token_value = token
+ return self
+
+ def request(self, request):
+ self.request_value = request
+ return self
+
+ def get_updates_request(self, request):
+ self.get_updates_request_value = request
+ return self
+
+ def proxy(self, _proxy):
+ raise AssertionError("builder.proxy should not be called when request is set")
+
+ def get_updates_proxy(self, _proxy):
+ raise AssertionError("builder.get_updates_proxy should not be called when request is set")
+
+ def build(self):
+ return self.app
+
+
+@pytest.mark.asyncio
+async def test_start_uses_request_proxy_without_builder_proxy(monkeypatch) -> None:
+ config = TelegramConfig(
+ enabled=True,
+ token="123:abc",
+ allow_from=["*"],
+ proxy="http://127.0.0.1:7890",
+ )
+ bus = MessageBus()
+ channel = TelegramChannel(config, bus)
+ app = _FakeApp(lambda: setattr(channel, "_running", False))
+ builder = _FakeBuilder(app)
+
+ monkeypatch.setattr("nanobot.channels.telegram.HTTPXRequest", _FakeHTTPXRequest)
+ monkeypatch.setattr(
+ "nanobot.channels.telegram.Application",
+ SimpleNamespace(builder=lambda: builder),
+ )
+
+ await channel.start()
+
+ assert len(_FakeHTTPXRequest.instances) == 1
+ assert _FakeHTTPXRequest.instances[0].kwargs["proxy"] == config.proxy
+ assert builder.request_value is _FakeHTTPXRequest.instances[0]
+ assert builder.get_updates_request_value is _FakeHTTPXRequest.instances[0]
+
+
+def test_derive_topic_session_key_uses_thread_id() -> None:
+ message = SimpleNamespace(
+ chat=SimpleNamespace(type="supergroup"),
+ chat_id=-100123,
+ message_thread_id=42,
+ )
+
+ assert TelegramChannel._derive_topic_session_key(message) == "telegram:-100123:topic:42"
+
+
+def test_get_extension_falls_back_to_original_filename() -> None:
+ channel = TelegramChannel(TelegramConfig(), MessageBus())
+
+ assert channel._get_extension("file", None, "report.pdf") == ".pdf"
+ assert channel._get_extension("file", None, "archive.tar.gz") == ".tar.gz"
+
+
+def test_is_allowed_accepts_legacy_telegram_id_username_formats() -> None:
+ channel = TelegramChannel(TelegramConfig(allow_from=["12345", "alice", "67890|bob"]), MessageBus())
+
+ assert channel.is_allowed("12345|carol") is True
+ assert channel.is_allowed("99999|alice") is True
+ assert channel.is_allowed("67890|bob") is True
+
+
+def test_is_allowed_rejects_invalid_legacy_telegram_sender_shapes() -> None:
+ channel = TelegramChannel(TelegramConfig(allow_from=["alice"]), MessageBus())
+
+ assert channel.is_allowed("attacker|alice|extra") is False
+ assert channel.is_allowed("not-a-number|alice") is False
+
+
+@pytest.mark.asyncio
+async def test_send_progress_keeps_message_in_topic() -> None:
+ config = TelegramConfig(enabled=True, token="123:abc", allow_from=["*"])
+ channel = TelegramChannel(config, MessageBus())
+ channel._app = _FakeApp(lambda: None)
+
+ await channel.send(
+ OutboundMessage(
+ channel="telegram",
+ chat_id="123",
+ content="hello",
+ metadata={"_progress": True, "message_thread_id": 42},
+ )
+ )
+
+ assert channel._app.bot.sent_messages[0]["message_thread_id"] == 42
+
+
+@pytest.mark.asyncio
+async def test_send_reply_infers_topic_from_message_id_cache() -> None:
+ config = TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], reply_to_message=True)
+ channel = TelegramChannel(config, MessageBus())
+ channel._app = _FakeApp(lambda: None)
+ channel._message_threads[("123", 10)] = 42
+
+ await channel.send(
+ OutboundMessage(
+ channel="telegram",
+ chat_id="123",
+ content="hello",
+ metadata={"message_id": 10},
+ )
+ )
+
+ assert channel._app.bot.sent_messages[0]["message_thread_id"] == 42
+ assert channel._app.bot.sent_messages[0]["reply_parameters"].message_id == 10
diff --git a/nanobot/tests/test_tool_validation.py b/nanobot/tests/test_tool_validation.py
new file mode 100644
index 0000000..c2b4b6a
--- /dev/null
+++ b/nanobot/tests/test_tool_validation.py
@@ -0,0 +1,339 @@
+from typing import Any
+
+from nanobot.agent.tools.base import Tool
+from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.agent.tools.shell import ExecTool
+
+
+class SampleTool(Tool):
+ @property
+ def name(self) -> str:
+ return "sample"
+
+ @property
+ def description(self) -> str:
+ return "sample tool"
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string", "minLength": 2},
+ "count": {"type": "integer", "minimum": 1, "maximum": 10},
+ "mode": {"type": "string", "enum": ["fast", "full"]},
+ "meta": {
+ "type": "object",
+ "properties": {
+ "tag": {"type": "string"},
+ "flags": {
+ "type": "array",
+ "items": {"type": "string"},
+ },
+ },
+ "required": ["tag"],
+ },
+ },
+ "required": ["query", "count"],
+ }
+
+ async def execute(self, **kwargs: Any) -> str:
+ return "ok"
+
+
+def test_validate_params_missing_required() -> None:
+ tool = SampleTool()
+ errors = tool.validate_params({"query": "hi"})
+ assert "missing required count" in "; ".join(errors)
+
+
+def test_validate_params_type_and_range() -> None:
+ tool = SampleTool()
+ errors = tool.validate_params({"query": "hi", "count": 0})
+ assert any("count must be >= 1" in e for e in errors)
+
+ errors = tool.validate_params({"query": "hi", "count": "2"})
+ assert any("count should be integer" in e for e in errors)
+
+
+def test_validate_params_enum_and_min_length() -> None:
+ tool = SampleTool()
+ errors = tool.validate_params({"query": "h", "count": 2, "mode": "slow"})
+ assert any("query must be at least 2 chars" in e for e in errors)
+ assert any("mode must be one of" in e for e in errors)
+
+
+def test_validate_params_nested_object_and_array() -> None:
+ tool = SampleTool()
+ errors = tool.validate_params(
+ {
+ "query": "hi",
+ "count": 2,
+ "meta": {"flags": [1, "ok"]},
+ }
+ )
+ assert any("missing required meta.tag" in e for e in errors)
+ assert any("meta.flags[0] should be string" in e for e in errors)
+
+
+def test_validate_params_ignores_unknown_fields() -> None:
+ tool = SampleTool()
+ errors = tool.validate_params({"query": "hi", "count": 2, "extra": "x"})
+ assert errors == []
+
+
+async def test_registry_returns_validation_error() -> None:
+ reg = ToolRegistry()
+ reg.register(SampleTool())
+ result = await reg.execute("sample", {"query": "hi"})
+ assert "Invalid parameters" in result
+
+
+def test_exec_extract_absolute_paths_keeps_full_windows_path() -> None:
+ cmd = r"type C:\user\workspace\txt"
+ paths = ExecTool._extract_absolute_paths(cmd)
+ assert paths == [r"C:\user\workspace\txt"]
+
+
+def test_exec_extract_absolute_paths_ignores_relative_posix_segments() -> None:
+ cmd = ".venv/bin/python script.py"
+ paths = ExecTool._extract_absolute_paths(cmd)
+ assert "/bin/python" not in paths
+
+
+def test_exec_extract_absolute_paths_captures_posix_absolute_paths() -> None:
+ cmd = "cat /tmp/data.txt > /tmp/out.txt"
+ paths = ExecTool._extract_absolute_paths(cmd)
+ assert "/tmp/data.txt" in paths
+ assert "/tmp/out.txt" in paths
+
+
+# --- cast_params tests ---
+
+
+class CastTestTool(Tool):
+ """Minimal tool for testing cast_params."""
+
+ def __init__(self, schema: dict[str, Any]) -> None:
+ self._schema = schema
+
+ @property
+ def name(self) -> str:
+ return "cast_test"
+
+ @property
+ def description(self) -> str:
+ return "test tool for casting"
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return self._schema
+
+ async def execute(self, **kwargs: Any) -> str:
+ return "ok"
+
+
+def test_cast_params_string_to_int() -> None:
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"count": {"type": "integer"}},
+ }
+ )
+ result = tool.cast_params({"count": "42"})
+ assert result["count"] == 42
+ assert isinstance(result["count"], int)
+
+
+def test_cast_params_string_to_number() -> None:
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"rate": {"type": "number"}},
+ }
+ )
+ result = tool.cast_params({"rate": "3.14"})
+ assert result["rate"] == 3.14
+ assert isinstance(result["rate"], float)
+
+
+def test_cast_params_string_to_bool() -> None:
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"enabled": {"type": "boolean"}},
+ }
+ )
+ assert tool.cast_params({"enabled": "true"})["enabled"] is True
+ assert tool.cast_params({"enabled": "false"})["enabled"] is False
+ assert tool.cast_params({"enabled": "1"})["enabled"] is True
+
+
+def test_cast_params_array_items() -> None:
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {
+ "nums": {"type": "array", "items": {"type": "integer"}},
+ },
+ }
+ )
+ result = tool.cast_params({"nums": ["1", "2", "3"]})
+ assert result["nums"] == [1, 2, 3]
+
+
+def test_cast_params_nested_object() -> None:
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {
+ "config": {
+ "type": "object",
+ "properties": {
+ "port": {"type": "integer"},
+ "debug": {"type": "boolean"},
+ },
+ },
+ },
+ }
+ )
+ result = tool.cast_params({"config": {"port": "8080", "debug": "true"}})
+ assert result["config"]["port"] == 8080
+ assert result["config"]["debug"] is True
+
+
+def test_cast_params_bool_not_cast_to_int() -> None:
+ """Booleans should not be silently cast to integers."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"count": {"type": "integer"}},
+ }
+ )
+ result = tool.cast_params({"count": True})
+ assert result["count"] is True
+ errors = tool.validate_params(result)
+ assert any("count should be integer" in e for e in errors)
+
+
+def test_cast_params_preserves_empty_string() -> None:
+ """Empty strings should be preserved for string type."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"name": {"type": "string"}},
+ }
+ )
+ result = tool.cast_params({"name": ""})
+ assert result["name"] == ""
+
+
+def test_cast_params_bool_string_false() -> None:
+ """Test that 'false', '0', 'no' strings convert to False."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"flag": {"type": "boolean"}},
+ }
+ )
+ assert tool.cast_params({"flag": "false"})["flag"] is False
+ assert tool.cast_params({"flag": "False"})["flag"] is False
+ assert tool.cast_params({"flag": "0"})["flag"] is False
+ assert tool.cast_params({"flag": "no"})["flag"] is False
+ assert tool.cast_params({"flag": "NO"})["flag"] is False
+
+
+def test_cast_params_bool_string_invalid() -> None:
+ """Invalid boolean strings should not be cast."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"flag": {"type": "boolean"}},
+ }
+ )
+ # Invalid strings should be preserved (validation will catch them)
+ result = tool.cast_params({"flag": "random"})
+ assert result["flag"] == "random"
+ result = tool.cast_params({"flag": "maybe"})
+ assert result["flag"] == "maybe"
+
+
+def test_cast_params_invalid_string_to_int() -> None:
+ """Invalid strings should not be cast to integer."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"count": {"type": "integer"}},
+ }
+ )
+ result = tool.cast_params({"count": "abc"})
+ assert result["count"] == "abc" # Original value preserved
+ result = tool.cast_params({"count": "12.5.7"})
+ assert result["count"] == "12.5.7"
+
+
+def test_cast_params_invalid_string_to_number() -> None:
+ """Invalid strings should not be cast to number."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"rate": {"type": "number"}},
+ }
+ )
+ result = tool.cast_params({"rate": "not_a_number"})
+ assert result["rate"] == "not_a_number"
+
+
+def test_validate_params_bool_not_accepted_as_number() -> None:
+ """Booleans should not pass number validation."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"rate": {"type": "number"}},
+ }
+ )
+ errors = tool.validate_params({"rate": False})
+ assert any("rate should be number" in e for e in errors)
+
+
+def test_cast_params_none_values() -> None:
+ """Test None handling for different types."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "count": {"type": "integer"},
+ "items": {"type": "array"},
+ "config": {"type": "object"},
+ },
+ }
+ )
+ result = tool.cast_params(
+ {
+ "name": None,
+ "count": None,
+ "items": None,
+ "config": None,
+ }
+ )
+ # None should be preserved for all types
+ assert result["name"] is None
+ assert result["count"] is None
+ assert result["items"] is None
+ assert result["config"] is None
+
+
+def test_cast_params_single_value_not_auto_wrapped_to_array() -> None:
+ """Single values should NOT be automatically wrapped into arrays."""
+ tool = CastTestTool(
+ {
+ "type": "object",
+ "properties": {"items": {"type": "array"}},
+ }
+ )
+ # Non-array values should be preserved (validation will catch them)
+ result = tool.cast_params({"items": 5})
+ assert result["items"] == 5 # Not wrapped to [5]
+ result = tool.cast_params({"items": "text"})
+ assert result["items"] == "text" # Not wrapped to ["text"]