CoreRasurae
07d104f831
Implemented three missing built-in resource tools from the specification: - builtin/file-move: Move/rename files within sandbox boundaries using shutil.move with path traversal protection. Validates source exists and is a regular file, rejects directory destinations with clear error messages. Creates destination parent directories automatically. - builtin/dir-create: Create directories with optional parent creation using Path.mkdir with sandbox validation. Returns accurate "created" field (false when directory already existed). Rejects paths that are existing regular files with a descriptive error. - builtin/file-info: Retrieve comprehensive file metadata (size, permissions, timestamps, type, encoding) with ISO 8601 formatted dates. Uses st_birthtime when available (macOS/BSD) with st_ctime fallback (Linux). Permissions return only permission bits via stat.S_IMODE. Encoding detection validates UTF-8 decoding before reporting "utf-8"; returns null for binary, non-UTF-8, or directory paths. All tools follow the existing ToolSpec pattern with proper JSON Schema definitions, capability metadata, and sandbox root validation. Added to ALL_FILE_TOOLS and registration helpers. Updated ChangeSetCapture to correctly track move operations: the wrapped handler now detects move tools by tool name (consistent with _detect_operation) and computes before/after hashes from the correct paths. Added "move" detection to _detect_operation so file-move entries get operation="move" (mapped to ChangeOperation.RENAME) instead of the incorrect "modify" fallback. Fixed _file_hash to skip directories (returns None) preventing IsADirectoryError when dir-create is wrapped by ChangeSetCapture during plan execution. Removed sandbox_root from new tool input_schemas to align with the 6 existing file tools which also omit it from their schemas. Tests: 22 Behave BDD scenarios (up from 7), Robot integration tests with on_timeout=kill, ASV benchmarks. Added path traversal tests for all three tools, overwrite behavior test, existing directory test, directory move rejection test, non-existent source test, directory destination rejection test, changeset integration tests for file-move and dir-create, binary file encoding test, permissions format test, and destination parent directory creation test. Review fixes applied (PR #1070 review): | # | Finding | Resolution | |---|---------|------------| | P1-1 | _file_hash crashes on directories | Added p.is_dir() guard | | P2-1 | file-move incorrect dest for dir targets | Reject directory destinations | | P2-2 | Changeset move detection via input fields | Use tool_spec.name instead | | P2-3 | st_ctime mislabeled as "created" on Linux | Use st_birthtime with fallback | | P2-4 | _detect_operation returns "modify" for no-op | Handle created=False + null hashes | | P2-5 | permissions includes file type bits | Use stat.S_IMODE() | | P2-6 | _detect_encoding reports utf-8 for non-UTF-8 | Validate with chunk.decode("utf-8") | | P3-1 | dir-create FileExistsError on regular file | Explicit pre-check with ValueError | | P3-2 | Misleading error for non-existent source | Separate exists/is_file checks | ISSUES CLOSED: #883
CleverAgents Core
CleverAgents is a Python-first automation platform. It provides a unified agents CLI, embedded runtime, and service orchestration tools while embracing modern Python tooling.
Highlights
- Unified CLI entry points:
cleveragentsandagents - Fast Typer/Click-based interface with parity for help/version behavior
- Behavior-driven coverage via Behave and Robot Framework
- Nox automation for linting, typing, testing, docs, builds, and benchmarks
- MkDocs-powered documentation with CleverAgents branding
Quick Start
# clone the CleverAgents core repository
git clone https://git.cleverthis.com/cleveragents/core.git
cd core
# install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,tests,docs]"
# set up pre-commit hooks and verify tooling
bash scripts/setup-dev.sh
# verify the CLI
agents --help
agents --version
Developing
Pre-commit hooks run automatically on every git commit (formatting, linting, type
checking, security scanning). To run checks manually:
# core validation
nox -s format # ruff auto-formatting
nox -s lint # ruff linting
nox -s typecheck # pyright type checking
nox -s unit_tests # behave unit tests
nox -s integration_tests # robot integration tests
# quality & security
nox -s security_scan # bandit security scanning
nox -s dead_code # vulture dead code detection
nox -s complexity # radon complexity analysis
nox -s pre_commit # run all pre-commit hooks
nox -s adr_compliance # verify ADR compliance
For the full quality automation guide, see docs/development/quality-automation.md.
Documentation
nox -s docs
nox -s serve_docs
Tests
Behave feature scenarios live under features/ and Robot suites under robot/. Use the Nox sessions above to execute them in parity with the implementation plan.
Observability
LangSmith tracing is optional and off by default. Enable it by exporting CLEVERAGENTS_LANGSMITH_ENABLED=true along with a project name and API key (CLEVERAGENTS_LANGSMITH_PROJECT, CLEVERAGENTS_LANGSMITH_API_KEY). The settings module automatically mirrors these values to LANGCHAIN_TRACING_V2, LANGCHAIN_PROJECT, and LANGCHAIN_API_KEY, so LangChain/LangGraph agents emit traces without extra wiring. Additional knobs such as CLEVERAGENTS_LANGSMITH_ENDPOINT, CLEVERAGENTS_LANGSMITH_USER_ID, and CLEVERAGENTS_LANGSMITH_TAGS are documented in docs/observability.md.
LLM provider configuration
CleverAgents ships with a LangChain/LangGraph powered provider registry that discovers whichever API keys you export and automatically selects the best available provider. The CLI now uses actors: select an actor with --actor <name> (or set a default via agents actor set-default). Actors embed provider/model choices; built-in actors are seeded from CLEVERAGENTS_DEFAULT_PROVIDER / CLEVERAGENTS_DEFAULT_MODEL, then fall back to the built-in order (openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini).
Required environment variables
| Provider | Primary variables |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
GOOGLE_API_KEY or GOOGLE_GENAI_API_KEY |
|
| Azure OpenAI | AZURE_OPENAI_API_KEY plus AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENT |
| OpenRouter | OPENROUTER_API_KEY (+ optional CLEVERAGENTS_OPENROUTER_ORGANIZATION for sanitized headers) |
| Gemini | GEMINI_API_KEY or GOOGLE_GEMINI_API_KEY |
| Cohere | COHERE_API_KEY |
| Groq | GROQ_API_KEY |
| Together | TOGETHER_API_KEY |
Set CLEVERAGENTS_DEFAULT_PROVIDER to pin the global provider (for example export CLEVERAGENTS_DEFAULT_PROVIDER=openai) and CLEVERAGENTS_DEFAULT_MODEL to lock in a model ID. When unset, the registry picks the first configured provider and uses its published default model such as gpt-4o for OpenAI or claude-sonnet-4-20250514 for Anthropic.
Diagnostics and testing shortcuts
agents diagnosticsprints whether the registry can see your credentials and which actor/provider is selected.agents tellandagents buildrequire--actor <name>unless a default actor is set; useagents actor set-default <name>to configure one.- Built-in actors (
<provider>/<model>) are immutable, custom actors must be namedlocal/<id>, and the default actor cannot be removed. Use--unsafewhen adding/updating configs marked unsafe; runtime only warns when invoking unsafe actors. CLEVERAGENTS_TESTING_USE_MOCK_AI=trueforces the in-repo mock provider so Behave/Robot suites never hit external APIs.- The full capability matrix (streaming, tool calls, JSON mode, etc.) is documented in
docs/reference/providers.md.