Metadata-Version: 2.4
Name: guardian-agent-runtime
Version: 0.1.0
Summary: Dedicated runtime for Guardian helper-backed standalone skills.
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: structlog>=24.4.0
Provides-Extra: browser
Requires-Dist: browser-use>=0.8.8; extra == 'browser'
Description-Content-Type: text/markdown

# Guardian Agent Runtime

This directory defines the dedicated runtime distribution for helper-backed
standalone skills.

## Purpose

`guardian-agent-runtime` is intentionally narrower than the full `qip`
application package. It exists so target-generic helper-backed skills such as:

- `guardian-live-browser-explorer`
- `guardian-shannon-pentester`

can be installed on a fresh machine without shipping the entire QIP backend/API
application as the default runtime surface.

## Build Model

The wheel is built by `scripts/build_agent_runtime_package.py`, which stages only
the browser/Shannon helper module closure plus the minimal shared/domain support
files required by those runtimes.

This is an explicit packaging boundary, not a second hand-edited source tree.

## Supported Distribution Flows

### Local / Manual Install

The recommended human-operated path is a GitLab project deploy token, not a
borrowed OAuth token from `glab`.

1. Create a project deploy token with:
   - `read_package_registry` for installs
   - `write_package_registry` too if you also want local manual publishes
2. Export:

```bash
export QIP_AGENT_RUNTIME_GITLAB_PROJECT_ID=79817094
export QIP_AGENT_RUNTIME_REGISTRY_USERNAME=<deploy-token-username>
export QIP_AGENT_RUNTIME_REGISTRY_PASSWORD=<deploy-token-secret>
```

3. Install the helper-backed runtime you need:

```bash
python3 scripts/install_helper_backed_skill_runtime.py --skill live-browser-explorer --gitlab-project-id "$QIP_AGENT_RUNTIME_GITLAB_PROJECT_ID"
python3 scripts/install_helper_backed_skill_runtime.py --skill shannon-pentester --gitlab-project-id "$QIP_AGENT_RUNTIME_GITLAB_PROJECT_ID"
```

If you already have a fully authenticated simple-index URL, the older
`QIP_AGENT_RUNTIME_INDEX_URL` path still works via:

```bash
python3 scripts/install_helper_backed_skill_runtime.py \
  --skill live-browser-explorer \
  --index-url "$QIP_AGENT_RUNTIME_INDEX_URL"
```

but it is no longer the preferred operator UX.

### Local / Manual Publish

Use the same deploy token, but expose the package-write credential through the
publish helper:

```bash
export QIP_AGENT_RUNTIME_GITLAB_PROJECT_ID=79817094
export QIP_AGENT_RUNTIME_PUBLISH_USERNAME=<deploy-token-username>
export QIP_AGENT_RUNTIME_DEPLOY_TOKEN=<deploy-token-secret>

python3 scripts/publish_agent_runtime_package.py \
  --gitlab-project-id "$QIP_AGENT_RUNTIME_GITLAB_PROJECT_ID" \
  --username "$QIP_AGENT_RUNTIME_PUBLISH_USERNAME" \
  --password-env QIP_AGENT_RUNTIME_DEPLOY_TOKEN
```

### Automated CI Publish

The long-term automated path is GitLab CI with `CI_JOB_TOKEN`.

- Root `.gitlab-ci.yml` includes `gitlab-templates/qip-agent-runtime.yml`
- Set `QIP_AGENT_RUNTIME_PUBLISH=true`
- Run the `qip:runtime-publish` job on `main` or publish automatically on a tag

The CI job resolves the package endpoint from `CI_PROJECT_ID` and
`CI_API_V4_URL` and authenticates with `gitlab-ci-token` plus `CI_JOB_TOKEN`.
