docs/hf-external-integrations.md

Deterministic HF external integrations

Starting source SHA: 8ca0c0d20ebf045fb2e62905176546a11e507dcb. Branch: jules/argus-openoperator-supervisor; review remains PR #29, no merge. Final committed delivery SHA is recorded in the PR and delivery message.

Runtime and token authority

helpers.runtime.is_huggingface_space() detects nonblank SPACE_ID, the documented Space variable. HF_SPACE does not control detection. This is not authentication; requires_auth and csrf_protect have no HF bypass. Browser settings/message endpoints retain normal session/login and CSRF behavior. External /api/settings_probe and /api/api_message retain API-key auth without browser cookies or CSRF.

Set the operator-owned HF secret SPYNEL_AGENT_ZERO_API_KEY before releasing. Use a random value chosen/stored by the operator. It is the shared incoming API/MCP/A2A credential; this change never invents or reveals a production key. On a Space, no canonical key means missing authority even if old settings or A0_SET_MCP_SERVER_TOKEN exist. MCP/A2A are disabled and external key endpoints return 503 with a safe missing-token diagnostic. The UI can still boot.

Locally the order remains deployment secret → persisted environment A0_SET_MCP_SERVER_TOKEN → configured token → stable generated local token. Source diagnostics use only deployment_secret, persisted_environment, configured, generated_local, missing. Generated local authority never counts as production-ready on a Space.

The HF entrypoint explicitly sets both MCP and A2A enabled flags according to canonical-secret presence and prints only a safe enabled/disabled message. Settings normalization enforces the same rule, protecting against stale persistent flags. The real key remains masked as ************ in settings output. Safe metadata is available through authenticated browser settings additional.external_services and API-key-protected settings_probe external_services: presence, source, effective enabled flags and a missing-token diagnostic. Neither tokens nor hashes are returned; /health remains source provenance only.

Connections

Replace YOUR_SPYNEL_AGENT_ZERO_API_KEY in the examples with the value you stored as the HF secret. The token is intentionally not retrievable from OpenOperator. The UI never substitutes the settings mask into an executable connection example.

• External API: POST /api/settings_probe or /api/api_message, header X-API-KEY: YOUR_SPYNEL_AGENT_ZERO_API_KEY.
• A2A: /a2a with Authorization: Bearer YOUR_SPYNEL_AGENT_ZERO_API_KEY or X-API-KEY, or compatible /a2a/t-YOUR_SPYNEL_AGENT_ZERO_API_KEY path.
• MCP SSE: /mcp/t-YOUR_SPYNEL_AGENT_ZERO_API_KEY/sse.
• MCP streamable HTTP: /mcp/t-YOUR_SPYNEL_AGENT_ZERO_API_KEY/http.

Existing MCP uses token-path routing, not newly invented header auth. A2A retains both header modes and token-path compatibility. All use the existing port 7860. Never post the real URLs/headers/tokens in chat, logs or Argus evidence.

Exact-SHA deployment

scripts/deploy_hf_space.py checks tracked and untracked worktree changes before any upload and refuses dirty state. There is no implicit dirty-tree override. It resolves the requested commit to its full SHA, prints local HEAD, deployment SHA, clean state and HF target, then archives only that commit. A historical --sha is explicitly identified. openoperator-build.json records that exact resolved SHA. The HF credential stays in the subprocess environment/askpass channel, not a credential-bearing Git remote URL or printed transport output.

After a clean commit and authorized branch push:

python scripts/deploy_hf_space.py \
  --sha <approved-full-source-sha> --space Leon4gr45/openoperator --verify

The operator must configure the canonical secret in the HF Space first. Authenticated upload also needs HF_TOKEN with write access to that Space. Provide credentials through secure environment bindings, never command arguments or chat. Successful push alone is not qualification. --verify requires live https://leon4gr45-openoperator.hf.space/health to report the exact requested SHA; a mismatch/unavailable health returns failure. A build may still be starting, so retry the read-only health verification after readiness instead of treating push success as a successful rollout. No merge or main-source push is required for this explicitly authorized feature-branch snapshot.

Local qualification

25 new tests cover documented detection, local/HF resolution priorities, missing canonical secret, effective flags/masking/diagnostics, normal HTTP browser and external API routing, CSRF, A2A Bearer/header/path auth, both MCP path transports, wrong credentials, MCP missing-token refusal, actual HF entrypoint settings logic, tracked/untracked dirty refusal, committed historical archive identity and exact health-SHA comparison. API-message model execution is controlled in the auth test; this proves authentication/dispatch, not a live model response. MCP downstream protocol work is controlled; routing/auth and middleware are real.

Final broad selection: 532 passed, zero failed/skipped, including all 25 new checks and the existing 507-test Argus/reliability selection.

ARGUS_TEST_ARGUS_PYTHON=/workspace/venvs/argus/bin/python \
ARGUS_TEST_FOREMAN_PYTHON=/workspace/venvs/foreman/bin/python \
/workspace/venvs/openoperator/bin/python -m pytest \
  plugins/argus_supervisor/tests tests/test_hf_integration_auth.py \
  plugins/_chat_naming/tests plugins/_goal/tests \
  tests/test_spynel.py tests/test_spynel_resolver.py \
  tests/test_spynel_dispatch_integration.py tests/test_spynel_profile_guard.py \
  tests/test_search_reliability.py tests/test_tinyfish_fallback.py \
  tests/test_document_query_plugin.py tests/test_document_query_fallback.py \
  tests/test_hf_deployment_control.py tests/test_hf_searxng_startup.py \
  tests/test_specialist_profiles.py tests/test_subagent_profiles.py \
  tests/test_hf_space_defaults.py tests/test_prompt_improver.py tests/test_colab_a0.py \
  tests/test_blocking_a2a.py tests/test_fasta2a_server.py tests/test_fasta2a_client.py \
  tests/test_goal_state_contract.py tests/test_http_auth_csrf.py \
  tests/test_api_token_authority.py tests/test_sidebar_row_actions.py \
  tests/test_settings_probe.py tests/test_runtime_dockerized.py \
  tests/test_settings_root_password.py tests/test_settings_mcp.py tests/test_hf_smoke.py \
  tests/test_memory_extension_hf.py tests/test_webui_icons.py \
  tests/test_tiny_coder_model_binding.py tests/test_worktree_isolation_contract.py -q
/workspace/venvs/openoperator/bin/ruff check \
  scripts/deploy_hf_space.py tests/test_hf_integration_auth.py
bash -n docker/run/fs/exe/huggingface-entrypoint.sh

Compilation of changed Python modules, JavaScript syntax checks of the three changed example scripts and whitespace checks also pass. Existing helper modules have unrelated pre-existing Ruff findings; no blanket helper-lint pass is claimed.

Live observations and blockers (17 October 2026)

Read-only public HF access succeeded. The SDK reports the Space RUNNING and HF repository commit 644af8260f54d0646f4aa6edab5904efa4f1b1a9. That is the HF repository SHA, not a proven deployed GitHub source SHA. The committed openoperator-build.json lookup returned 404. Live /health also returned 404, so no running-source identity could be proven.

Live probe	Observed result
Browser POST /api/settings_get, no login	302; browser auth still enforced
POST /api/settings_probe, wrong key	401
POST /api/api_message, wrong key	401
A2A discovery, wrong X-API-KEY	401
MCP HTTP, wrong token path	403
Correct-token settings_probe/api_message	Not run: canonical credential unavailable
Authenticated A2A discovery/harmless task	Not run: canonical credential unavailable
Authenticated MCP SSE/HTTP negotiation	Not run: canonical credential unavailable
Requested source SHA deployed and health matched	Not performed/qualified

The local environment has no HF_TOKEN or canonical integration-token binding. Hugging Face SDK whoami() confirms LocalTokenNotFoundError, so public reads do not establish write authentication. Canonical secret presence in the HF Space cannot be established without authorized credential metadata access. No secret value was requested in chat, generated, logged, retrieved from settings or changed in HF. Secure optional cloud binding requirements have been saved for review; that does not populate values, apply/publish configuration or configure HF secrets.

Deployment is authorized by this follow-up but blocked by those concrete prerequisites. The operator must set SPYNEL_AGENT_ZERO_API_KEY in HF, bind a write-scoped HF_TOKEN for upload, and bind the same canonical secret securely for external acceptance tests. No upload/rebuild/restart/merge was performed. After access is supplied, deploy the final committed SHA, wait for the exact health SHA, then test correct-token API responses, one harmless A2A request and both MCP transports; repeat wrong-token and browser-protection checks. Until then this is locally qualified code with partial live negative-auth evidence, not a qualified production deployment.