82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# Agent Instructions
|
|
|
|
## Goals
|
|
- Keep runtime behavior explicit and predictable.
|
|
- Keep integration points documented when features are added.
|
|
- Enforce a consistent quality gate before merging changes.
|
|
|
|
## Project Organization
|
|
- `src/agents`: session lifecycle, limits, resource provisioning, and schema-driven orchestration.
|
|
- `src/mcp`: MCP config types, conversion, and handler policy resolution.
|
|
- `src/examples`: provider-specific execution entrypoints.
|
|
- `tests`: focused unit tests for orchestration and config behavior.
|
|
|
|
## Engineering Standards
|
|
- TypeScript strict mode stays enabled.
|
|
- Exported interfaces should be typed explicitly and validated at boundaries.
|
|
- New behavior should include at least one test if it changes control flow or config parsing.
|
|
- Avoid provider-specific policy in shared modules unless there is a clear extension point.
|
|
- **When adding new runtime limits or resource constraints, ensure they are added to `.env.example`.**
|
|
|
|
## Runtime Environment Variables
|
|
- Agent manager limits:
|
|
- `AGENT_MAX_CONCURRENT`
|
|
- `AGENT_MAX_SESSION`
|
|
- `AGENT_MAX_RECURSIVE_DEPTH`
|
|
- Orchestration/context limits:
|
|
- `AGENT_STATE_ROOT`
|
|
- `AGENT_PROJECT_CONTEXT_PATH`
|
|
- `AGENT_TOPOLOGY_MAX_DEPTH`
|
|
- `AGENT_TOPOLOGY_MAX_RETRIES`
|
|
- `AGENT_RELATIONSHIP_MAX_CHILDREN`
|
|
- `AGENT_MERGE_CONFLICT_MAX_ATTEMPTS`
|
|
- Provisioning/resource controls:
|
|
- `AGENT_WORKTREE_ROOT`
|
|
- `AGENT_WORKTREE_BASE_REF`
|
|
- `AGENT_WORKTREE_TARGET_PATH`
|
|
- `AGENT_PORT_BASE`
|
|
- `AGENT_PORT_BLOCK_SIZE`
|
|
- `AGENT_PORT_BLOCK_COUNT`
|
|
- `AGENT_PORT_PRIMARY_OFFSET`
|
|
- `AGENT_PORT_LOCK_DIR`
|
|
- `AGENT_DISCOVERY_FILE_RELATIVE_PATH`
|
|
- Security middleware controls:
|
|
- `AGENT_SECURITY_VIOLATION_MODE`
|
|
- `AGENT_SECURITY_ALLOWED_BINARIES`
|
|
- `AGENT_SECURITY_COMMAND_TIMEOUT_MS`
|
|
- `AGENT_SECURITY_AUDIT_LOG_PATH`
|
|
- `AGENT_SECURITY_ENV_INHERIT`
|
|
- `AGENT_SECURITY_ENV_SCRUB`
|
|
- `AGENT_SECURITY_DROP_UID`
|
|
- `AGENT_SECURITY_DROP_GID`
|
|
- Runtime-injected resource context (provided by provisioning; do not set in `.env`):
|
|
- `AGENT_REPO_ROOT`
|
|
- `AGENT_WORKTREE_PATH`
|
|
- `AGENT_WORKTREE_BASE_REF`
|
|
- `AGENT_PORT_RANGE_START`
|
|
- `AGENT_PORT_RANGE_END`
|
|
- `AGENT_PORT_PRIMARY`
|
|
- `AGENT_DISCOVERY_FILE`
|
|
|
|
## Documentation Standards
|
|
- Update `README.md` for user-facing behavior.
|
|
- **Update this file for any new environment variables related to agent context or limits.**
|
|
- Add design/maintenance notes in `docs/` for non-trivial architecture decisions.
|
|
|
|
## Quality Gate
|
|
|
|
Run this before opening a PR:
|
|
|
|
```bash
|
|
npm run verify
|
|
```
|
|
|
|
Equivalent individual commands:
|
|
|
|
```bash
|
|
npm run check
|
|
npm run check:tests
|
|
npm run test
|
|
npm run build
|
|
```
|