AGENTS.md · qhkm/zeptoclaw

Sections

1. Project Snapshot
2. Task Tracking Protocol
3. Post-Implementation Checklist
4. File Ownership Rules (for parallel agents)
5. Required Quality Gates
6. Coding Rules
7. Runtime and Provider Notes
8. Documentation Rules
9. Release Versioning
10. Change Hygiene
11. Common Patterns

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

Project-level guidance for coding agents working in this repository.

## Project Snapshot

- Language: Rust (edition 2021)
- Core binary: `zeptoclaw` (`src/main.rs` thin entrypoint; CLI handlers in `src/cli/`); stripped release size budgets are **11MB on linux-x86_64** and **7MB on aarch64**, checked locally when relevant; escape valve for genuine new heavy deps is feature-gating, not bumping the budget
- Extra binary: `benchmark` (`src/bin/benchmark.rs`)
- Benchmarks: `benches/message_bus.rs`
- Integration tests: `tests/integration.rs`
- Agent coding benchmark fixture: `test-coding/` with intentionally buggy Python code and stdlib verification tests
- Pristine agent comparison fixture: `test-coding-pristine/` preserves the original failing state for repeatable head-to-head runs
- Codebase: ~154,000 lines of Rust under `src/`
- Channels: 10 active built-ins (Telegram, Slack, Discord, WhatsApp Web, WhatsApp Cloud, Lark, Email, Webhook, Serial, ACP); MQTT code is present but the Cargo feature is parked until `rumqttc` no longer pins the vulnerable `rustls-webpki`
- Runtimes: 6 (Native, Docker, Apple Container, Landlock, Firejail, Bubblewrap)
- Peripherals: 4 boards (ESP32, RPi, Arduino, Nucleo) with GPIO, I2C, NVS, Serial
- Skills: OpenClaw-compatible (reads `metadata.zeptoclaw` > `metadata.openclaw` > raw)
- Plugins: Command-mode (shell template) + Binary-mode (JSON-RPC 2.0 stdin/stdout)
- Library facade: `ZeptoAgent::builder()` for embedding as a crate (Tauri, GUI apps)
- Runtime provider resolution: builds chain in registry order only when `providers.fallback.enabled`; honors `providers.fallback.provider`; can wrap chain with `RetryProvider` via `providers.retry.*`
- Provider introspection CLI: `zeptoclaw provider status` prints resolved providers, wrapper config (retry/fallback), and quota usage snapshot
- Provider onboarding validation: Anthropic uses `GET /v1/models`; OpenAI-compatible presets validate keys with read-only endpoint checks, including Zhipu/GLM via `GET /models`
- Model discoverability hardening: gateway-style slash IDs (for example `anthropic/...`) only infer OpenRouter when that provider is actually available, and live `/model fetch` now honors `api_version` while normalizing Azure deployment bases to `/openai/models`
- OpenAI-compatible serve tool calling: `/v1/chat/completions` forwards request tools to providers, returns assistant/tool messages plus tool-call payloads in OpenAI format, streams tool-call deltas even for providers using the default `chat_stream()` adapter, and rejects unsupported `tool_choice` values instead of silently ignoring them
- Interactive `zeptoclaw agent` UI (#721) lives in `cli::{ui, markdown, term}`: one task renders tool feedback and the reply in order (`with_feedback` in `cli/agent.rs`), the `StatusLine` spinner shares a lock with every printed line and clears synchronously, replies are indented/word-wrapped markdown (incremental for streaming), and each turn ends with a `model · tokens · tools · time` footer. Piped stdout gets the raw reply; `NO_COLOR`/`TERM=dumb` disable styling. Control characters in model output are stripped before rendering.
- `zeptoclaw serve` auth (#713): with `ZEPTOCLAW_SERVE_API_KEY` / `--api-key` set, every `/v1/*` request needs `Authorization: Bearer <key>`; without a key the command refuses non-loopback binds unless `--insecure-no-auth`. See `api::serve::{build_serve_router, check_bind_security}`; body limit is the shared 1 MiB `api::server::API_BODY_LIMIT_BYTES`
- Channel dispatch: avoids holding the channels map `RwLock` across async `send()` awaits
- Channel supervisor: polling (15s) detects dead channels, restarts with 60s cooldown, max 5 restarts
- Channel panic isolation: Slack/Discord/Webhook/WhatsApp/WhatsApp Web/WhatsApp Cloud/Lark/Email/Serial spawned tasks are wrapped with `catch_unwind` and panic logging; MQTT code remains present while its Cargo feature is parked
- Webhook auth hardening: generic webhook supports optional HMAC-SHA256 body signatures plus fixed server-side sender/chat identity by default (`trust_payload_identity` is an explicit legacy escape hatch); WhatsApp Cloud verifies `X-Hub-Signature-256` when `app_secret` is configured
- Telegram allowlist hardening: numeric user IDs are the safe default for new setups; legacy username matching remains available only through `channels.telegram.allow_usernames` for compatibility and emits warnings when non-numeric allowlist entries are present
- Telegram config compatibility: `channels.telegram` accepts legacy `bot_token`, `allowed_senders`, and `allowed_chats` keys, and auto-enables when `enabled` is omitted but a Telegram token is present
- Email allowlist limitation surfaced: `channels.email.allowed_senders` matches the parsed `From` header only and now emits config/runtime warnings so authenticated-mail enforcement is pushed upstream
- Telegram outbound formatting: sends HTML parse mode with `||spoiler||` → `<tg-spoiler>` conversion
- Telegram response streaming: opt-in `channels.telegram.streaming` routes provider deltas through cumulative outbound stream phases, edits UTF-16-safe previews at a bounded cadence, preserves reply/topic routing, and falls back to a fresh final HTML message after preview failures
- Discord outbound delivery: supports reply references and thread-create metadata (`discord_thread_*`) in `OutboundMessage`
- Cron scheduling hardening: dispatch timeout + exponential error backoff + one-shot delete-after-run only on success
- Model switching: Telegram `/model` supports per-chat overrides (in-memory + long-term)
- Persona switching: `/persona` command with presets and custom text, LTM persistence per chat
- CLI interactive mode: TTY-gated local slash commands with rustyline tab completion when available, persisted REPL history, inline tool approval prompts, session-scoped `/trust` override for local use, `/model` and `/persona` overrides, `/tools`, `/template`, and `/clear`
- Memory injection: per-message query-matched injection via shared LTM on `AgentLoop` (startup static injection removed)
- Prompt envelope (#661): the system prompt is byte-stable (no live clock, no query memory); `ContextBuilder::build_turn_context()` renders the clock + memory once per turn into a `<turn-context>` block prepended to a request copy of the latest user message (persisted history stays clean). `ToolRegistry` is a `BTreeMap`, so tool definitions are name-sorted. The Claude provider adds up to 4 `cache_control` breakpoints (system or last tool, plus trailing messages) to the serialized request copy and debug-logs cache read/write tokens; only the first `System` message becomes Claude's `system` field, later notices ride as user-turn text after tool results. `Usage.prompt_tokens` includes cache reads/writes (folded in via `Usage::with_cache()`, split kept in `cache_read_tokens`/`cache_creation_tokens`), so token budgets and metrics see the full prompt; `utils::cost::estimate_usage_cost()` bills cache reads at 0.1x and writes at 1.25x the input rate (#711).
- Long-term memory tool guidance: `longterm_memory` now advertises explicit use/counter-use trigger phrases so agents persist durable corrections and preferences without duplicating repo docs or task-scoped context
- Tool execution convergence: agent loop, MCP server, and embedded `ZeptoAgent` facade all route through `kernel::execute_tool()` (shared safety scan + taint checks + single metrics recording); the facade also enforces per-tool timeout, panic capture, and optional approval handling for embedded coding backends
- Coding tool hardening: `grep` now surfaces subprocess failures instead of silently returning "No matches"; `shell` truncates output at 2,000 lines / 50KB; `edit_file` rejects empty `old_text` and supports optional `expected_replacements` for safer surgical edits
- Tool composition: natural language tool creation with `{{param}}` template interpolation
- Filesystem hardening: filesystem write/edit tools now create parent directories one component at a time inside the workspace and use secure no-follow writes; mount validation rejects Unix regular-file mounts with multiple hard links in both blocked-path and allowlist flows; safety pre-scan keeps full path scanning while scanning file bodies with a narrow `shell_injection` carve-out instead of skipping content wholesale
- Secret storage hardening: config and panel token writes use user-only permissions on Unix (0600 files and 0700 ZeptoClaw directories) and repair permissions left by older versions
- Panel auth hardening: static bearer tokens use constant-time comparison, WebSocket connections exchange them for bounded 30-second single-use tickets, and CLI output points to the token file instead of printing the secret
- Safer default execution posture: fresh configs now start in `agent_mode = "assistant"` with approvals enabled under the `require_for_dangerous` policy
- Gateway startup guard: degrade after N crashes to prevent crash loops
- Loop guard: SHA256 tool-call repetition detection with warn + circuit-breaker stop
- In-memory audit hash-chain: `src/audit.rs` appends SHA-256-linked entries (`record_audit_chain_event`, `verify_audit_chain_integrity`, `recent_audit_entries`, `audit_tip_hash`), and `kernel::execute_tool()` now emits tool execution chain events with shell/network/spawn classification
- Tool execution hardening: per-tool-call timeout + panic capture in both `process_message` and `process_message_streaming` tool `join_all` paths
- Runtime subprocess hardening: Native, Docker, Apple Container, Landlock, Firejail, and Bubblewrap scrub secret-like inherited environment variables by default; `runtime.env_passthrough` explicitly opts names back in, Unix timeouts terminate/reap the process group, and timed-out Docker containers are force-removed
- Streaming tool parity: `process_message_streaming()` now mirrors non-streaming hook callbacks, usage-metric accounting, success/failure logging, thinking/response feedback, and malformed tool-argument parse preservation
- Context trimming: normal/emergency/critical compaction tiers (70%/90%/95%)
- Session repair: auto-fixes orphan tool results, empty/duplicate messages, alternation issues
- r8r bridge: optional WebSocket client for workflow approvals, health updates, and replay-safe duplicate-event acknowledgments
- Config hot-reload: gateway polls config mtime every 30s and applies provider/channel/safety updates
- Config validation: `zeptoclaw config check` recognizes top-level `tunnel` and `r8r_bridge`, plus agent defaults such as `timezone`, `tool_timeout_secs`, and `system_prompt`
- Validation runs locally; GitHub Actions CI, E2E, and PR hygiene workflows are removed. Optional feature paths require local checks when changed; tag-triggered release and Docker publishing remain enabled
- Dependency audit baseline: `cargo deny check` passes with patched `anyhow` 1.0.103, `bcrypt` 0.19.2, `chacha20` 0.10.2, `crossbeam-epoch` 0.9.20, `h2` 0.4.19, `quinn-proto` 0.11.15, `quick-xml` 0.41, `lopdf` 0.42, and `rustls` 0.23.45 (RUSTSEC-2026-0285)
- Tool-schema repair: `utils::tool_schema` sanitizes outbound schemas in `ToolRegistry::definitions*()` (illegal property keys, `type` arrays, bare-string schemas, `$ref` siblings, top-level combinators, `properties` on bare object schemas for llama.cpp GBNF) and repairs inbound args at every nesting depth in `kernel::execute_tool()` via `unrename_tool_args()` + `coerce_tool_args()`; never rewrites a string the schema already permits, so `"07030"` survives a `["string","integer"]` union
- Reasoning models: `reasoning_content` (non-stream + stream delta) and `finish_reason` are parsed on the OpenAI-compatible path; `resolve_assistant_text()` falls back to reasoning only when there is no content and no tool calls, warning with `finish_reason`. Reasoning deltas never stream as reply text. `ChatOptions::with_reasoning_effort()` sets `reasoning_effort`, omitted when unset
- MCP transport: supports both HTTP and stdio MCP servers (`url` or `command` + args/env) with tool registration during `create_agent()`
- Hands-lite: `HAND.toml` + bundled hands (`researcher`, `coder`, `monitor`) + `hand` CLI
- Panel CLI fallback: feature-disabled builds still parse `zeptoclaw panel ...` and return explicit `--features panel` guidance instead of a raw unknown-subcommand error
- Uninstall CLI: `zeptoclaw uninstall` removes `~/.zeptoclaw`; `--remove-binary` deletes direct installs in `~/.local/bin` or `/usr/local/bin` and defers Homebrew/Cargo binaries to their package managers
- Process exit codes: explicit `main` mapping for success (0) and error (1); uncaught panic/crash remains Rust default (101)
- Tests: current local validation passes `cargo fmt -- --check`, `cargo clippy -- -D warnings`, `cargo nextest run --lib` (3531 passed, 6 skipped), and `cargo test --doc` (128 passed, 27 ignored)

## Task Tracking Protocol

**Every session MUST track work via GitHub Issues.**

1. **Start of session** — Run `gh issue list --state open --limit 20` and present open issues
2. **New work** — If no issue exists for the requested work, create one with `gh issue create` before writing code. Use labels: type (`bug`/`feat`/`rfc`/`chore`/`docs`), area (`area:tools`/`area:channels`/etc.), priority (`P1`/`P2`/`P3`)
3. **End of work** — Create PR with `Closes #N` in body, or `gh issue close N` for direct commits
4. **NEVER merge PRs** — Only the user merges PRs. After creating a PR, present the URL and local validation results to the user, and only merge after explicit user approval

Skip issue creation only for trivial changes (typo fixes, one-line tweaks).

## Post-Implementation Checklist

**After completing ANY feature, you MUST:**

1. **Close the GitHub issue** — `Closes #N` in PR or `gh issue close N`
2. **`CLAUDE.md`** — update architecture tree, test counts, module descriptions, new CLI flags
3. **`AGENTS.md`** (this file) — update project snapshot above

If you skip this, the next agent starts with stale context and wastes time.

## File Ownership Rules (for parallel agents)

To avoid merge conflicts when multiple agents work simultaneously:

| Zone | Files | Rule |
|------|-------|------|
| **Shared (wire last)** | `src/main.rs`, `src/config/types.rs`, `*/mod.rs` | Only ONE agent touches these. Wiring done after all parallel work finishes. |
| **Provider** | `src/providers/<name>.rs` | One agent per provider file. |
| **Tool** | `src/tools/<name>.rs` | One agent per tool file. |
| **Utils** | `src/utils/<name>.rs` | One agent per util file. |
| **New files** | Any new `*.rs` | Safe — no conflicts if it's a new file. |

## Required Quality Gates

Before finishing any non-trivial change, run:

```bash
cargo fmt -- --check
cargo clippy -- -D warnings
cargo nextest run --lib
cargo test --doc
```

If benchmark-related code is changed, also run:

```bash
cargo bench --bench message_bus --no-run
```

## Coding Rules

- Keep changes minimal and focused.
- Prefer small, composable functions over large blocks.
- Do not add `unwrap()`/`expect()` in production paths unless failure is truly unrecoverable.
- Preserve existing module boundaries and public APIs unless explicitly requested.
- Keep comments short and only where intent is non-obvious.

## Runtime and Provider Notes

- Runtime isolation features must remain opt-in and degrade safely to native runtime.
- Provider wiring should remain consistent across config, onboarding, status output, and runtime behavior.
- Do not hardcode a single provider path when multiple providers are supported.

## Documentation Rules

- Keep README/docs claims aligned with executable behavior.
- Do not add performance numbers unless they are reproducible with repository commands.
- If adding new commands or workflows, include a runnable example.

## Release Versioning

- Use `patch` for backward-compatible bug fixes, reliability hardening, docs corrections, and internal refactors that do not add user-visible capability.
- Use `minor` for backward-compatible new functionality such as new commands, flags, config fields, tools, providers, runtimes, channels, or other opt-in capabilities.
- If upgrading should only give existing users fixes, choose `patch`.
- If upgrading gives existing users new capabilities without requiring migration, choose `minor`.

## Change Hygiene

- Do not revert unrelated local changes.
- If you detect unexpected file modifications during work, pause and ask before proceeding.
- Include file/line references when reporting review findings.

## Common Patterns

### Adding a config field
1. Add field + doc comment to struct in `src/config/types.rs`