Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (99 loc) · 4.52 KB

AGENTS.md

File metadata and controls

124 lines (99 loc) · 4.52 KB
Raw

AGENTS.md

Guidance for coding agents working in this repository.

Project Overview

Hiro is an experimental AI-assisted penetration testing and CTF workflow platform. It combines:

  • FastAPI backend in server/
  • Vue 3 frontend in web/
  • DeepAgents-based session runtime in server/agent/
  • SQLAlchemy models in server/models/
  • REST and WebSocket APIs in server/api/v1/endpoints/
  • RAG, MCP, and specialized workflow agents

Treat security-sensitive behavior with care. Hiro can execute model-directed tools and shell commands, so do not broaden execution, persistence, or auth behavior without a clear reason.

Repository Layout

.
|-- main.py                    # Backend entrypoint
|-- pyproject.toml             # Python metadata and dependencies
|-- server/                    # FastAPI app, models, services, agent runtime
|   |-- agent/                 # Runtime, streaming, persistence, tools, subagents
|   |-- api/v1/endpoints/      # REST and WebSocket endpoints
|   |-- core/                  # Settings, security, installation, utilities
|   |-- models/                # SQLAlchemy ORM models
|   `-- service/               # RAG and MCP services
|-- tests/                     # Backend tests
|-- web/                       # Vue frontend
|   |-- src/components/        # Reusable Vue components
|   |-- src/pages/             # Page-level views
|   |-- src/types/             # Frontend TypeScript types
|   `-- package.json           # Frontend scripts
`-- skills/                    # DeepAgent skill instructions

Common Commands

Backend:

uv sync
uv run python main.py
uv run pytest
uv run pytest tests/test_session_stats.py

Frontend:

cd web
bun install
bun run dev
bun run build

Use Bun for frontend dependency management and scripts in this workspace.

Development Notes

  • Python requires 3.12 or newer.
  • Backend dependencies are managed by uv.
  • Frontend is Vue 3 + TypeScript + Vite, run through Bun.
  • The frontend build runs vue-tsc -b && vite build.
  • The default local API runs at http://localhost:8000.
  • Vite development server proxies /api to the backend by default.
  • There is no Alembic migration setup. Existing lightweight schema updates are handled during startup in server/app.py.

Backend Conventions

  • Keep API schemas in server/schemas/ synchronized with SQLAlchemy models and frontend types.
  • Session and agent behavior mostly lives in server/api/v1/endpoints/session.py, server/agent/custom_agent.py, and server/agent/runtime/.
  • Token usage normalization is centralized in server/agent/persistence/token_usage.py; reuse it instead of duplicating provider-specific accounting rules.
  • Message persistence and history reconstruction live in server/agent/persistence/message_store.py.
  • Prefer narrow helper functions near the endpoint/runtime code they support.
  • Preserve WebSocket event names and payload shapes unless updating the frontend at the same time.

Frontend Conventions

  • Reuse existing UI primitives under web/src/components/ui/.
  • Keep session-related state and orchestration in web/src/pages/SessionPage.vue unless there is a clear component boundary.
  • Keep TypeScript response types in web/src/types/agent.ts aligned with backend schemas.
  • Use existing component patterns for settings, tabs, cards, and icon buttons.
  • Run bun run build after frontend type or template changes.

Testing Guidance

  • Add focused backend tests under tests/ for backend logic changes.
  • For token accounting, cover cached token edge cases because providers report cache reads differently.
  • For endpoint behavior, prefer small helper-level tests when the helper contains the business rule; add API-level tests when request/response semantics matter.
  • For frontend changes, bun run build is the baseline verification.

Security And Data Handling

  • Do not commit .env, local databases, RAG stores, generated session data, API keys, tokens, or captured target artifacts.
  • Keep auth, installation, command execution, MCP, and file-access changes tightly scoped.
  • Do not weaken sandboxing or command validation without explicit justification.
  • Assume generated commands and agent outputs may contain sensitive or unsafe content.

Working With Existing Changes

  • The worktree may contain user edits. Do not revert unrelated changes.
  • Before editing a file, inspect the local context and preserve existing style.
  • Keep diffs focused on the requested task.
  • If a build creates web/dist/, do not commit it unless explicitly requested.