zeptoclaw: Instructions file for Codex

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