diff --git a/.github/copilot-instructions.md.bak.1771326435 b/.github/copilot-instructions.md.bak.1771326435 deleted file mode 100644 index cb438a420..000000000 --- a/.github/copilot-instructions.md.bak.1771326435 +++ /dev/null @@ -1,194 +0,0 @@ -# Agent Instructions - -Gradle-based multi-module project in Kotlin. Emphasizes centralized build configurations, custom -plugins, and version catalogs. - -## Core Principles - -> **⚠️ CRITICAL: Security First, Performance Second** -> -> Every decision, every line of code, every architecture choice MUST prioritize: -> -> 1. **Security First** - Always think about attacks, vulnerabilities, and safe defaults -> - Never trust user input - - - Use parameterized queries, never string concatenation for SQL - - Validate and sanitize all data - - Follow principle of least privilege - - Keep dependencies updated to patch security vulnerabilities - -> 2. **Extreme Performance Second** - Optimize for efficiency after security -> - Think about algorithmic complexity (O(n) vs O(n²)) -> - Avoid unnecessary allocations -> - Use lazy initialization when appropriate -> - Profile before optimizing - measure don't guess -> - Consider memory footprint and startup time -> -> These principles override convenience, speed of development, and "getting it done quickly." - -## Quick Commands - -```bash -# Build & Run -make build # Full build with tests -make build-fast # Build without tests -make run # Run Compose desktop app -./gradlew composeApp:run # Direct Gradle - -# Testing -make test # All tests -make test-app # Single module -./gradlew :composeApp:jvmTest --tests "ClassName.methodName" # Single test -./gradlew :composeApp:jvmTest --tests "*Pattern*" # Pattern match -make test-coverage # With Kover report -make test-verbose # --info output - -# Code Quality -make format # Spotless apply -make check-format # Spotless check -make lint-kotlin # Detekt analysis -make lint-java # SpotBugs analysis -make check # All checks - -# Maintenance -make clean # Clean build artifacts -make clean-all # Clean + Gradle cache -make deps # Show dependencies -make tasks # List all tasks -make info # Project info -``` - -## Code Style - -### Formatting (.editorconfig) - -- **Indent**: 2 spaces (no tabs) -- **Max line**: 100 characters -- **Trailing commas**: Required -- **No wildcard imports**: Explicit only -- **Charset**: UTF-8, trim whitespace, final newline - -### Kotlin Patterns - -```kotlin -// Data classes with value classes -data class User( - val id: UserId, - val name: String, - val createdAt: Instant = Instant.now(), -) - -@JvmInline -value class UserId(val value: UUID) - -// Sealed types for results -sealed interface Result { - data class Success(val data: T) : Result - data class Failure(val error: Throwable) : Result -} - -// Null safety - NO !! operator -val name = user?.name ?: "Unknown" -requireNotNull(value) { "Required" } - -// Expression bodies -fun double(x: Int): Int = x * 2 -``` - -### Naming - -- **Classes**: PascalCase (`UserService`) -- **Functions**: camelCase (`findById`) -- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRY`) -- **Tests**: Backticks `` `should work` `` -- **Booleans**: `is`/`has` prefix (`isActive`) - -### Error Handling - -```kotlin -// Result for recoverable -fun find(id: UUID): Result = runCatching { - repo.find(id) ?: throw NotFoundException(id) -} - -// Sealed exceptions -sealed class DomainError(msg: String) : RuntimeException(msg) -class NotFoundException(id: UUID) : DomainError("Not found: $id") -``` - -## Gradle Guidelines - -### Best Practices - -- Use `tasks.register` not `create` (lazy) -- Use `configureEach` not `all` -- Never use `afterEvaluate` -- Avoid `project` in task actions -- Annotate task inputs/outputs for caching - -### Dependencies - -```kotlin -// Version catalog -implementation(libs.slf4j.api) -testImplementation(libs.junit.jupiter) -``` - -## Project Structure - -``` -├── apps/ -│ ├── composeApp/ # Shared Kotlin Multiplatform Compose UI module -│ ├── androidApp/ # Native Android host app for Compose -│ ├── iosApp/ # Native iOS host app for Compose -│ └── docs/ # Documentation website -├── modules/ -│ ├── agent-core-kmp/ # Shared Kotlin Multiplatform core -│ └── agent-core-rust/ # Embedded Rust AI core -├── gradle/ -│ ├── build-logic/ # Custom plugins -│ └── libs.versions.toml # Version catalog -└── settings.gradle.kts -``` - -## Available Skills - -Located in `.agents/skills/`. Reference for detailed patterns: - -| Skill | Description | Trigger | -| -------------------------------------------------------------------- | ----------------------------------------- | -------------------------------- | -| [gradle](.agents/skills/gradle/SKILL.md) | Gradle best practices, custom tasks | `build.gradle.kts`, build config | -| [kotlin](.agents/skills/kotlin/SKILL.md) | Kotlin conventions, null safety | `.kt` files | -| [c4-diagrams](.agents/skills/c4-diagrams/SKILL.md) | C4 architecture diagrams | `docs/architecture/diagrams` | -| [pr-creator](.agents/skills/pr-creator/SKILL.md) | PR creation workflow | Creating PRs | -| [pinned-tag](.agents/skills/pinned-tag/SKILL.md) | Pin GitHub Actions | CI security | -| [release](.agents/skills/release/SKILL.md) | Release process, Maven Central publishing | Creating releases | -| [android-expert](.agents/skills/android-expert/SKILL.md) | Android-specific patterns, best practices | Android development | -| [compose-expert](.agents/skills/compose-expert/SKILL.md) | Jetpack Compose UI patterns | Compose UI code | -| [desktop-expert](.agents/skills/desktop-expert/SKILL.md) | Compose Desktop, desktop patterns | Desktop app development | -| [gradle-expert](.agents/skills/gradle-expert/SKILL.md) | Advanced Gradle, custom plugins | Complex Gradle configs | -| [kotlin-coroutines](.agents/skills/kotlin-coroutines/SKILL.md) | Coroutines, async patterns | Coroutines, Flow | -| [kotlin-expert](.agents/skills/kotlin-expert/SKILL.md) | Advanced Kotlin features | Advanced Kotlin | -| [kotlin-multiplatform](.agents/skills/kotlin-multiplatform/SKILL.md) | KMP patterns, expect/actual | KMP modules | - -## Testing - -```kotlin -class ServiceTest { - @Test - fun `should return result`() { - val result = service.action() - assertEquals(expected, result) - } -} -``` - -Run specific test: - -```bash -./gradlew :composeApp:jvmTest --tests "*ComposeAppCommonTest*" -``` - -## License - -Apache 2.0 - See LICENSE file diff --git a/.github/rulesets/minor-protection.json b/.github/rulesets/minor-protection.json index 6d6632f80..1aceb3da7 100644 --- a/.github/rulesets/minor-protection.json +++ b/.github/rulesets/minor-protection.json @@ -34,8 +34,13 @@ { "type": "required_status_checks", "parameters": { - "required_status_checks": [], - "strict_required_status_checks_policy": false + "required_status_checks": [ + { + "context": "core-check", + "integration_id": 15368 + } + ], + "strict_required_status_checks_policy": true } }, { diff --git a/clients/agent-runtime/AGENTS.md b/clients/agent-runtime/AGENTS.md new file mode 100755 index 000000000..d9e0d5a95 --- /dev/null +++ b/clients/agent-runtime/AGENTS.md @@ -0,0 +1,158 @@ +# AGENTS.md — Agent Coding Guide + +This file defines the default working protocol for coding agents in this repository. +Scope: clients/agent-runtime (Rust agent-runtime module). + +## 1) Project Snapshot (Read First) + +Corvus is a Rust-first autonomous agent runtime optimized for: + +- high performance +- high efficiency +- high stability +- high extensibility +- high sustainability +- high security + +Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules. + +Key extension points: + +- `src/providers/traits.rs` (`Provider`) +- `src/channels/traits.rs` (`Channel`) +- `src/tools/traits.rs` (`Tool`) +- `src/memory/traits.rs` (`Memory`) +- `src/observability/traits.rs` (`Observer`) +- `src/runtime/traits.rs` (`RuntimeAdapter`) + +## 2) Repository Map (High-Level) + +- `src/main.rs` — CLI entrypoint and command routing +- `src/lib.rs` — module exports and shared command enums +- `src/config/` — schema + config loading/merging +- `src/agent/` — orchestration loop +- `src/gateway/` — webhook/gateway server +- `src/security/` — policy, pairing, secret store +- `src/memory/` — markdown/sqlite memory backends + embeddings/vector merge +- `src/providers/` — model providers and resilient wrapper +- `src/channels/` — Telegram/Discord/Slack/etc channels +- `src/tools/` — tool execution surface (shell, file, memory, browser) +- `src/runtime/` — runtime adapters (currently native) +- `docs/` — architecture + process docs +- `.github/` — CI, templates, automation workflows + +## 3) Non-Negotiable Engineering Constraints + +### 3.1 Performance and Footprint + +- Prefer minimal dependencies; avoid adding crates unless clearly justified. +- Preserve release-size profile assumptions in `Cargo.toml`. +- Avoid unnecessary allocations, clones, and blocking operations. +- Keep startup path lean; avoid heavy initialization in command parsing flow. + +### 3.2 Security and Safety + +- Treat `src/security/`, `src/gateway/`, `src/tools/` as high-risk surfaces. +- Never broaden filesystem/network execution scope without explicit policy checks. +- Never log secrets, tokens, raw credentials, or sensitive payloads. +- Keep default behavior secure-by-default (deny-by-default where applicable). + +### 3.3 Stability and Compatibility + +- Preserve CLI contract unless change is intentional and documented. +- Prefer explicit errors over silent fallback for unsupported critical paths. +- Keep changes local; avoid cross-module refactors in unrelated tasks. + +## 4) Agent Workflow (Required) + +1. **Read before write** + - Inspect existing module and adjacent tests before editing. +2. **Define scope boundary** + - One concern per PR; avoid mixed feature+refactor+infra patches. +3. **Implement minimal patch** + - Follow KISS/YAGNI/DRY; no speculative abstractions. +4. **Validate by risk** + - Docs-only: keep checks lightweight. + - Code changes: run relevant checks and tests. +5. **Document impact** + - Update docs/PR notes for behavior, risk, rollback. + +## 5) Change Playbooks + +### 5.1 Adding a Provider + +- Implement `Provider` in `src/providers/`. +- Register in `src/providers/mod.rs` factory. +- Add focused tests for factory wiring and error paths. + +### 5.2 Adding a Channel + +- Implement `Channel` in `src/channels/`. +- Ensure `send`, `listen`, and `health_check` semantics are consistent. +- Cover auth/allowlist/health behavior with tests. + +### 5.3 Adding a Tool + +- Implement `Tool` in `src/tools/` with strict parameter schema. +- Validate and sanitize all inputs. +- Return structured `ToolResult`; avoid panics in runtime path. + +### 5.4 Security / Runtime / Gateway Changes + +- Include threat/risk notes and rollback strategy. +- Add or update tests for boundary checks and failure modes. +- Keep observability useful but non-sensitive. + +## 6) Validation Matrix + +Default local checks for code changes: + +```bash +cargo fmt --all -- --check +cargo clippy --all-targets -- -D warnings +cargo test +``` + +If full checks are impractical, run the most relevant subset and document what was skipped and why. + +For workflow/template-only changes, at least ensure YAML/template syntax validity. + +## 7) Collaboration and PR Discipline + +- Follow `.github/pull_request_template.md`. +- Keep PR descriptions concrete: problem, change, non-goals, risk, rollback. +- Use conventional commit titles. +- Prefer small PRs (`size: XS/S/M`) when possible. + +Reference docs: + +- `CONTRIBUTING.md` +- `docs/pr-workflow.md` + +## 8) Anti-Patterns (Do Not) + +- Do not add heavy dependencies for minor convenience. +- Do not silently weaken security policy or access constraints. +- Do not mix massive formatting-only changes with functional changes. +- Do not modify unrelated modules "while here". +- Do not bypass failing checks without explicit explanation. + +## 9) Handoff Template (Agent -> Agent / Maintainer) + +When handing off work, include: + +1. What changed +2. What did not change +3. Validation run and results +4. Remaining risks / unknowns +5. Next recommended action + +## 10) Vibe Coding Guardrails + +When working in a fast iterative "vibe coding" style: + +- Keep each iteration reversible (small commits, clear rollback). +- Validate assumptions with code search before implementing. +- Prefer deterministic behavior over clever shortcuts. +- Do not "ship and hope" on security-sensitive paths. +- If uncertain, leave a concrete TODO with verification context, not a hidden guess. diff --git a/clients/web/apps/docs/astro.config.mjs b/clients/web/apps/docs/astro.config.mjs index 1f810eca0..d6c4f8d1c 100644 --- a/clients/web/apps/docs/astro.config.mjs +++ b/clients/web/apps/docs/astro.config.mjs @@ -124,13 +124,6 @@ export default defineConfig({ es: 'Visión General', }, }, - { - label: 'C4 Diagrams', - slug: 'guides/architecture/index', - translations: { - es: 'Diagramas C4', - }, - }, ], }, ],