spec.md

# Spynel Hugging Face Deployment and Integration Contract

## Scope

This document is the source of truth for the Spynel deployment branch. Changes
must remain modular and minimize invasive changes to Agent Zero core behavior.

## Hugging Face Docker Space

- The root Docker image must run Agent Zero as a non-root UID/GID 1000 process.
- The WebUI must listen on `0.0.0.0:7860`, and port 7860 must be the only
  required published port.
- Startup must not require `chpasswd`, SSH, cron, supervisor, sudo, privileged
  Docker flags, or another root-only service.
- The Space image must retain the base image's `/ins/*` installers and copy only
  the HF-specific entrypoint from `docker/run/fs/`; installer and entrypoint
  scripts must fail build-time integrity checks for Git LFS pointer text or a
  missing shebang before any installer executes.
- Agent Zero application files must be readable by UID 1000. Runtime state and
  Hugging Face, XDG, and Matplotlib cache directories must be writable by UID
  1000.
- Kokoro, spaCy, their models, and other dependencies must be installed in a
  writable image-build layer. Runtime dependency installation must not be used
  to hide missing build dependencies or write into immutable image layers.
- Space startup errors must be fixed at their cause rather than suppressed.

## Administrative Profile Creation

- Provide an authenticated, CSRF-protected API for explicitly creating profiles
  under `usr/agents/` through existing profile persistence helpers.
- Validate profile names and prompt filenames, reject traversal/nested paths,
  reserved profiles, and duplicates, and preserve existing profile selection.
- Routing syntax must never invoke profile creation. An unknown routed profile
  must fail explicitly without creating a context or profile directory.

## Spynel Profile and Routing

Ship a bundled `spynel` Agent Zero profile with this routing grammar:

- `@profile`: route to an agent profile.
- `/sdk`: route to an SDK gateway.
- `@profile /sdk`: send profile metadata through the selected SDK gateway.
- No routing tokens: Spynel handles the request locally.

External routing contracts:

- `/sdk` resolves only from `SPYNEL_SDK_<SDK>_URL`.
- A registered `@profile` resolves only from `SPYNEL_AGENT_<PROFILE>_URL`.
- External destinations must be credential-free HTTPS URLs registered through
  environment variables; user text must never supply or override a destination.
- Dispatch uses shell-free curl argv execution, bounded connect/overall
  timeouts, terminate/kill cleanup, structured polling, progress states, and
  useful failure information.

Internal routing contracts:

- An unregistered `@profile` may select only an existing Agent Zero profile.
- Delegation uses configurable same-container loopback transport, preferably
  `SPYNEL_AGENT_ZERO_URL=http://127.0.0.1:7860`, authenticated with
  `SPYNEL_AGENT_ZERO_API_KEY`. HTTPS remains mandatory for non-loopback URLs.
- The Hugging Face entrypoint must configure Agent Zero's existing API-key
  verifier from `SPYNEL_AGENT_ZERO_API_KEY` without printing the secret.
- Delegation creates a fresh context, selects the requested profile, submits the
  stripped task asynchronously, polls with meaningful progression, and returns
  the result.
- Unknown profiles fail before context creation and are never implicitly
  created.

## Paperclip Skill

- Ship a Spynel-native Paperclip board-manager skill targeting
  `https://leon4gr45-paperclip-founder.hf.space` by default.
- Configuration uses `PAPERCLIP_BASE_URL` and optional
  `PAPERCLIP_API_TOKEN`.
- The helper permits credential-free HTTPS base URLs and confined `/api/*`
  paths, bounds timeouts, avoids shell interpolation, does not leak tokens, and
  preserves useful 401/403/404 response behavior.
- Live validation must use read-only requests unless disposable authenticated
  test data is explicitly available.

## Colab Lifecycle CLI

Provide a CLI that starts Agent Zero in the background, checks `/api/health`,
and stops the process group. It must handle stale PID files, graceful shutdown,
and bounded forced termination fallback.

## Required Validation

- Clean-build the actual root Docker image and run it without development bind
  mounts or privileged flags as UID/GID 1000.
- Verify `/api/health`, the UI root, authenticated API access, Spynel profile and
  profile-scoped skill discovery, administrative profile auth/CSRF, writable
  state/cache paths, and clean startup logs.
- Run internal Spynel delegation, explicit unknown-profile safety, controlled
  immediate/async HTTPS external fixtures, read-only live Paperclip checks,
  disposable profile creation, and the Colab lifecycle.
- Install the real framework dependencies and run the complete pytest suite plus
  focused Spynel, Python compilation, shell syntax, and diff checks.
- Do not claim Hugging Face readiness unless the image builds and the resulting
  non-root container successfully serves `/api/health`.