Spaces:
Running
Running
| # OpenOperator Hugging Face Space Deployment & Acceptance Contract | |
| ## 1. System Invariants | |
| OpenOperator enforces a strict separation between immutable application code and persistent user/runtime state: | |
| ```text | |
| green GitHub SHA | |
| == | |
| HF snapshot | |
| == | |
| /git/agent-zero | |
| == | |
| /a0 application code | |
| ``` | |
| while: | |
| ```text | |
| /a0/usr | |
| ``` | |
| remains persistent, mutable user state containing settings, goals, workdirs, logs, and `usr/.env`. | |
| --- | |
| ## 2. Exact Application Code Synchronization | |
| During container startup (`docker/run/fs/ins/copy_A0.sh`), exact application code is synchronized: | |
| ```bash | |
| rsync -a --delete --no-owner --no-group --exclude='/usr' /git/agent-zero/ /a0/ | |
| ``` | |
| - Application code in `/a0` is kept perfectly in sync with the build snapshot `/git/agent-zero`. | |
| - Obsolete application files removed from newer commits are pruned from `/a0`. | |
| - The user directory `/a0/usr` (and all subdirectories `/a0/usr/*`) is strictly excluded from deletion or overwrite. | |
| --- | |
| ## 3. Deployment Secret Mapping & Bridge | |
| Hugging Face Space Secrets arrive as process environment variables. Upon application startup, `helpers/runtime_secrets.py` normalizes and bridges these secrets into `/a0/usr/.env` with strict `0600` permissions. | |
| ### Secret Mapping Table | |
| | Space Secret Variable | Canonical Runtime Variable(s) | Purpose | | |
| |---|---|---| | |
| | `SPYNEL_AGENT_ZERO_API_KEY` | `SPYNEL_AGENT_ZERO_API_KEY` | Agent Zero internal API authentication (`X-API-KEY`) | | |
| | `HUGGINGFACE_TOKEN` | `HF_TOKEN` | Hugging Face CLI (`hf`) & remote Hugging Face MCP authorization | | |
| | `GITHUB_PAT` | `GH_TOKEN`, `GITHUB_TOKEN` | GitHub repository inspection, PR management & Git operations | | |
| ### Model Provider Secrets | |
| | Environment Variable | Canonical Runtime Setting | Purpose | | |
| |---|---|---| | |
| | `COMPATIBLE_URL` | `chat.api_base` | OpenAI-compatible LLM endpoint URL | | |
| | `COMPATIBLE_MODEL` | `chat.name` | OpenAI-compatible model name | | |
| | `BLABLADOR_API_KEY` | `API_KEY_OTHER` | Model API key stored securely outside presets in `.env` | | |
| ### Critical Credential Distinctions | |
| - `HF_TOKEN` (Hugging Face token) is **NOT** the LLM model API key. | |
| - `HF_TOKEN` is **NOT** the Spynel API key (`SPYNEL_AGENT_ZERO_API_KEY`). | |
| - `GITHUB_PAT` is **NOT** the Hugging Face token. | |
| ### Secret Hygiene & Rotation Rules | |
| 1. Space process environment variables override stale persisted values in `usr/.env` upon container restart. | |
| 2. Secret values are **NEVER** printed, logged, returned in `/health`, or exposed via settings APIs. | |
| 3. Diagnostic endpoints report boolean presence status only (`{"spynel_api_key": true, "hf_token": true, "github_token": true}`). | |
| --- | |
| ## 4. Deployed Source SHA Identity | |
| Every deployment snapshot includes `/openoperator-build.json` containing: | |
| ```json | |
| { | |
| "source_sha": "<full-github-commit-sha>" | |
| } | |
| ``` | |
| The application exposes this identity via: | |
| - `GET /health` -> `{"status": "ok", "sha": "<full-github-commit-sha>"}` | |
| Acceptance smoke testing compares `GET /health`'s reported SHA against the target green commit SHA. | |
| --- | |
| ## 5. Hugging Face MCP Client Integration | |
| OpenOperator connects to Hugging Face's official remote MCP server as a client: | |
| - **Endpoint**: `https://huggingface.co/mcp` | |
| - **Transport**: Streamable HTTP (`type: "streamable-http"`) | |
| - **Header Configuration**: `"Authorization": "Bearer ${ENV:HF_TOKEN}"` | |
| ### Safe Secret Interpolation | |
| - `helpers/mcp_handler.py` substitutes `${ENV:VAR_NAME}` placeholders in memory at request time. | |
| - Placeholders match `^[A-Z_][A-Z0-9_]*$` strictly. Arbitrary code execution or `eval` is prohibited. | |
| - Serialized `settings.json`, UI outputs, and logs preserve the literal placeholder `${ENV:HF_TOKEN}` and never log expanded secret tokens. | |
| - No local MCP daemon or additional listening port is executed (only public port `7860`). | |
| --- | |
| ## 6. Modern `hf` CLI Tooling | |
| The modern `hf` CLI (`huggingface_hub[cli]`) is installed at image build time in `/opt/venv-a0/bin/hf`: | |
| - Available on system `PATH`. | |
| - Authenticates seamlessly via `HF_TOKEN` in environment. | |
| - Commands utilized by OpenOperator: | |
| - `hf auth whoami` | |
| - `hf spaces info OWNER/SPACE` | |
| - `hf spaces logs OWNER/SPACE` | |
| - `hf spaces logs --build OWNER/SPACE` | |
| - `hf spaces secrets list OWNER/SPACE` | |
| --- | |
| ## 7. Specialist Profile Organization | |
| OpenOperator includes 19 native specialist profiles under `/a0/agents/`: | |
| 1. `developer` - Software architecture & master orchestration | |
| 2. `hacker` - Security research & parallel hypothesis testing | |
| 3. `spynel` - External API routing & task dispatch | |
| 4. `reviewer` - Read-only code & spec review | |
| 5. `tester` - Test suite execution & evidence verification | |
| 6. `tiny-coder` - Bounded 1-3 file patch implementation | |
| 7. `debugger` - Failure localization & falsifiable hypotheses | |
| 8. `integrator` - API contracts & protocol verification | |
| 9. `frontend-qa` - UI contrast & browser behavior verification | |
| 10. `evals` - Benchmark evaluation & performance metrics | |
| 11. `shipper` - Release preparation & production approval gate | |
| 12. `launch` - Launch storyboard & release notes | |
| 13. `performance` - Concurrency profiling & latency analysis | |
| 14. `security` - Surface security auditing & credential checks | |
| 15. `refactorer` - Structural changes & technical debt reduction | |
| 16. `maintainer` - Dependency updates & environment maintenance | |
| 17. `data-engineer` - Data pipeline & schema engineering | |
| 18. `docs` - Verified technical documentation | |
| 19. `repository-manager` - Git, GitHub PR, and Hugging Face Space management | |
| ### `repository-manager` Policy | |
| - **Default Mode**: Read-only inspection (`git status`, `git log`, `git diff`, `hf spaces info`, `hf spaces logs`, `hf spaces secrets list`). | |
| - **Mutation Policy**: Pushes, branch deletions, PR merges, Space variable changes, and deployments require explicit authorization. | |
| --- | |
| ## 8. Deployment & Acceptance Procedure | |
| ### Deployment Execution | |
| To deploy a verified green GitHub commit SHA to Hugging Face Space `Leon4gr45/openoperator`: | |
| ```bash | |
| export HF_TOKEN="<write-scoped-hf-token>" | |
| python3 scripts/deploy_hf_space.py --space Leon4gr45/openoperator --sha <green-commit-sha> | |
| ``` | |
| ### Live Acceptance Verification | |
| Once the Space rebuilds, run the acceptance smoke test: | |
| ```bash | |
| export SPYNEL_AGENT_ZERO_API_KEY="<deployment-secret>" | |
| export EXPECTED_OPENOPERATOR_SHA="<green-commit-sha>" | |
| python3 scripts/smoke_hf_openoperator.py --mode full --expected-sha <green-commit-sha> | |
| ``` | |
| Required Live Verification Checklist: | |
| - [x] Health status == PASS (`GET /health`) | |
| - [x] Deployed SHA matches expected GitHub commit SHA | |
| - [x] Specialist Profiles == PASS (all 19 profiles discoverable) | |
| - [x] Required Skills == PASS (all 23 skills present) | |
| - [x] Spynel Routing == PASS (`@repository-manager`, `@reviewer`, etc.) | |
| - [x] Goal Delegation == PASS (`/goal` execution with specialist profile) | |
| - [x] Unknown Profile Safety == PASS (404 on unknown profiles) | |
| - [x] API Token Masking == PASS (`mcp_server_token == "************"`) | |