mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-30 07:33:59 +08:00
45060f4492
* chore(gator): add gator gate skill * chore(gator): add sandbox launcher scaffold * chore(gator): add codex image and docs checks * chore(gator): fold approved provider policy rules * chore(gator): add deterministic reviewer runner * chore(gator): clarify ok-to-test comments * chore(gator): structure launcher harnesses * chore(gator): require e2e for dependabot * chore(gator): add codex refresh profile * chore(gator): wip manifest agent launcher * feat(agents): supervise watch cycles in sandbox * fix(agents): preserve gateway refresh state * fix(gator): continue human response threads * fix(agents): keep watch supervisor retrying * fix(agents): use refreshed Codex credential aliases * fix(gator): avoid misleading gh auth checks * docs(agents): remove architecture build update * fix(gator): use REST-backed GitHub writes * fix(agents): bake immutable agent payloads * fix(agents): upload writable agent workspace * fix(agents): surface gator watch progress * fix(agents): prevent codex stdin hang * fix(agents): align codex subagent input * fix(agents): heartbeat during active cycles * fix(agents): clean up heartbeat sleep * fix(agents): disable gh telemetry in codex harness * fix(agents): reconcile closed gator PRs * fix(agents): query closed gator PR labels separately * fix(agents): tolerate rotated credential placeholders * fix(agents): enforce gator same-sha comment guard Signed-off-by: John Myers <johntmyers@users.noreply.github.com> * docs(agents): scope gator trusted commentary Signed-off-by: John Myers <johntmyers@users.noreply.github.com> * fix(gator): treat reviewer failures as transient Signed-off-by: Evan Lezar <elezar@nvidia.com> * feat(agents): refine gator supervised workflow Signed-off-by: John Myers <johntmyers@users.noreply.github.com> * fix(agents): stream codex prompts via stdin Signed-off-by: John Myers <johntmyers@users.noreply.github.com> * docs(agents): clarify trusted gator responses Signed-off-by: John Myers <johntmyers@users.noreply.github.com> * refactor(agents): scope gator PR to scripts Signed-off-by: John Myers <johntmyers@users.noreply.github.com> --------- Signed-off-by: John Myers <johntmyers@users.noreply.github.com> Signed-off-by: Evan Lezar <elezar@nvidia.com> Co-authored-by: John Myers <johntmyers@users.noreply.github.com> Co-authored-by: Evan Lezar <elezar@nvidia.com>
54 lines
4.7 KiB
Markdown
54 lines
4.7 KiB
Markdown
# Gator Agent
|
|
|
|
Launch a headless sandbox agent that runs the `gator-gate` skill against OpenShell issues and pull requests. The default and currently only supported harness is Codex.
|
|
|
|
## Prerequisites
|
|
|
|
- `gh` is authenticated on the host and has access to `NVIDIA/OpenShell` and `NVIDIA/OpenShell-Community`.
|
|
- For `--harness codex`, `codex login` has created `$HOME/.codex/auth.json`.
|
|
- For `--harness codex`, local Codex auth must include an access token, refresh token, and account ID.
|
|
- A local gateway is available when using the default local Dockerfile source.
|
|
|
|
## Usage
|
|
|
|
```shell
|
|
./scripts/agents/run.sh \
|
|
--agent gator \
|
|
--gateway docker-dev \
|
|
--harness codex \
|
|
"Run gator on PR 1536 and keep watching until it closes or merges."
|
|
```
|
|
|
|
By default the launcher uses `scripts/agents/gator/Dockerfile` as the sandbox source. Local gateways build `scripts/agents/gator/` as the image context, so gator-specific image files such as `policy.yaml` and `bin/gh` stay with the gator agent. The launcher bakes rendered prompts, skills, subagents, and shared runtime files into `/etc/openshell/agent-payload`, so `--from` must point to a local Dockerfile or directory containing a Dockerfile.
|
|
|
|
Use `--harness codex` to select Codex explicitly. Other harness names are rejected until their support is added to `agent.yaml` and `scripts/agents/runtime/harnesses/<name>/`. Agent directories do not carry their own harness implementations; they provide prompt templates and optional skills or subagents for the shared runtime to inject.
|
|
|
|
Use `--codex-bin "$(command -v codex)"` only when the host executable is compatible with the sandbox OS and architecture.
|
|
|
|
The manifest-driven launcher at `scripts/agents/run.sh` reads `agent.yaml`, which defines the agent prompt template, provider profile IDs, provider credential sources, gateway settings, skills, subagents, sandbox defaults, runtime mode, and harness defaults. The shared sandbox entrypoint at `scripts/agents/runtime/entrypoint.sh` starts the in-sandbox supervisor, which invokes the selected harness adapter for bounded cycles.
|
|
|
|
The launcher:
|
|
|
|
- Scans `profile_paths` in manifest order and imports `providers/github-gator.yaml`.
|
|
- Creates or updates the `github-gator` provider from `gh auth token`.
|
|
- Selects the requested harness and bakes the common runtime into the immutable sandbox payload.
|
|
- For `--harness codex`, imports `providers/codex-gator.yaml`, creates or updates the `codex-gator` provider from `$HOME/.codex/auth.json`, and stores the refresh token as gateway-only refresh material.
|
|
- For `--harness codex`, configures gateway-managed refresh for `CODEX_AUTH_ACCESS_TOKEN` and rotates it before launching the sandbox.
|
|
- Enables `providers_v2_enabled`, `agent_policy_proposals_enabled`, and `proposal_approval_mode=auto` at gateway scope.
|
|
- Uses the gator image policy copied to `/etc/openshell/policy.yaml`.
|
|
- Installs the gator-specific `gh` wrapper from `gator/bin/gh` as `/usr/local/bin/gh` to prevent duplicate same-head-SHA gator dispositions.
|
|
- Bakes `scripts/agents/gator/skills/gator-gate/SKILL.md` into `/etc/openshell/agent-payload`.
|
|
- Bakes `.claude/agents/principal-engineer-reviewer.md` so the selected harness can run a deterministic independent reviewer execution through `/etc/openshell/agent-payload/runtime/subagent.sh principal-engineer-reviewer < task.md`.
|
|
- For `--harness codex`, optionally bakes a host Codex executable as `/etc/openshell/agent-payload/runtime/harnesses/codex/codex`.
|
|
- Starts the selected harness without a TTY.
|
|
- Runs gator in `watch` mode by default. The sandbox stays alive while the supervisor sleeps between bounded Codex cycles, so Codex is not connected during passive PR waits. The supervisor prints periodic heartbeat lines during active cycles and passive sleeps.
|
|
- Deletes the sandbox automatically after the supervisor exits. Pass `--keep` to preserve it for debugging.
|
|
|
|
The GitHub provider profile allows read-only GraphQL queries on `api.github.com/graphql` so `gh` read paths can use GraphQL when needed. Write operations remain REST-only and scoped to the two allowed repositories.
|
|
|
|
Set `GATOR_CODEX_ACCESS_CREDENTIAL_KEY` or pass `--codex-access-key` if the gator Codex profile uses a credential key other than `CODEX_AUTH_ACCESS_TOKEN` for the short-lived access token.
|
|
|
|
Use `--once` for a single reconciliation cycle. Use `--poll-interval <seconds>` to change the default 15-minute watch cadence.
|
|
|
|
The launcher preserves existing gateway-owned Codex refresh material by default so multiple gator sandboxes do not overwrite each other's refresh-token lineage from host Codex auth. If gateway rotation fails, the launcher automatically resets gateway refresh material from host Codex auth and retries once. After `codex logout && codex login`, you can also pass `--reset-refresh` to force that reset before rotation.
|