feat(agents): add manifest-driven gator agent by johntmyers · Pull Request #1826 · NVIDIA/OpenShell

johntmyers · 2026-06-09T05:15:13Z

Summary

Add a manifest-driven sandbox agent launcher and the first concrete agent, Gator, for validating and monitoring OpenShell issues and PRs. The launcher packages shared runtime adapters, provider profiles, skills, subagents, and prompts into supervised OpenShell sandboxes so gator can run bounded Codex cycles in watch mode.

Related Issue

None.

Changes

Add openshell-agents/run.sh, shared runtime entrypoint, supervisor, Codex harness adapter, and subagent dispatch support.
Add the openshell-agents/gator/ manifest, prompt, README, Dockerfile, scoped GitHub/Codex provider profiles, and sandbox policy.
Add the gator-gate skill for the gator state machine, validation rules, human-response disposition, reviewer invocation, CI/test gating, and scoped GitHub auth guidance.
Add gateway-managed Codex access-token refresh handling and preserve/repair behavior for long-running watch sandboxes.
Harden watch mode so transient transport failures, malformed cycle results, and legacy failure statuses retry without exiting the sandbox.
Document the agent runtime and provider placeholder behavior in openshell-agents/README.md.

Testing

mise run pre-commit passes
Unit tests added/updated
E2E tests added/updated (if applicable)

Additional checks:

bash openshell-agents/runtime/supervisor_test.sh
Live gator sandboxes relaunched and observed Ready on docker-dev
Verified provider-backed Codex and GitHub placeholder resolution inside gator sandboxes

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture docs updated (not applicable; agent docs live under openshell-agents/)

elezar · 2026-06-10T17:30:45Z

While exercising the gator state machine on #1850, I hit one transition that is worth clarifying in this PR.

When a PR is in gator:approval-needed and a maintainer approval arrives, gator currently re-checks the PR and stays in gator:approval-needed until the PR is merged or closed. Mechanically that is fine, but the label reads as if approval is still missing after approval has already been received.

Can we make this explicit in the gator support added here? Two reasonable options:

Document/comment-template wording: after approval, gator:approval-needed means "maintainer merge decision pending" for an open PR.
Add a distinct state such as gator:merge-ready or gator:merge-pending so the post-approval state is not overloaded.

The current behavior is not blocking #1850, but without this clarification users will reasonably ask why an approved PR still says approval-needed.

copy-pr-bot · 2026-06-10T19:46:11Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

github-actions · 2026-06-18T14:28:24Z

🌿 Preview your docs: https://nvidia-preview-pr-1826.docs.buildwithfern.com/openshell

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers · 2026-06-26T19:46:43Z

@drew @elezar refactored to be under scripts/agents and implemented other suggestions w/ the exception of factoring out Ruby. would like to just merge this so its at least in main and can iterate more later.

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

elezar · 2026-06-29T08:24:53Z

 where that socket directory is hidden before privilege drop.

-Credential placeholders in proxied HTTP requests can be resolved by the proxy
 when policy allows the target endpoint. For GCP providers, a loopback metadata


nit: This is now not a complete sentence.

elezar · 2026-06-29T08:29:35Z

    (is_service_name || is_cluster_local_service) && labels.iter().all(|label| !label.is_empty())
 }

+fn uses_reserved_placeholder_revision_namespace(key: &str) -> bool {


Are we ok duplicating this function accross the openshell-core and this crate? (It would be nice to at least use a consistent name though).

elezar

Thanks @johntmyers.

Happy to get this in and iterate further.

One question would be whether we want to pull out the changes to OpenShell into a more focussed PR and then add the agent skill here? Not a blocker though.

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers requested a review from a team as a code owner June 9, 2026 05:15

johntmyers requested review from derekwaynecarr and mrunalp as code owners June 9, 2026 15:09

elezar reviewed Jun 10, 2026

View reviewed changes

Comment thread scripts/agents/gator/Dockerfile

elezar reviewed Jun 10, 2026

View reviewed changes

Comment thread scripts/agents/run.sh

johntmyers force-pushed the feat/gator-gate-skill branch from a89ff4d to 9779477 Compare June 18, 2026 14:27

johntmyers requested a review from maxamillion as a code owner June 18, 2026 14:27

drew reviewed Jun 22, 2026

View reviewed changes

Comment thread scripts/agents/README.md

johntmyers added 19 commits June 26, 2026 12:23

chore(gator): add gator gate skill

343ff7e

chore(gator): add sandbox launcher scaffold

98d1487

chore(gator): add codex image and docs checks

f5e465f

chore(gator): fold approved provider policy rules

3641b0a

chore(gator): add deterministic reviewer runner

ec1a19d

chore(gator): clarify ok-to-test comments

726ac78

chore(gator): structure launcher harnesses

ef37c1f

chore(gator): require e2e for dependabot

5d5b754

chore(gator): add codex refresh profile

37867fa

chore(gator): wip manifest agent launcher

d92acb3

feat(agents): supervise watch cycles in sandbox

a045a25

fix(agents): preserve gateway refresh state

b9f6b3e

fix(gator): continue human response threads

09ac5d5

fix(agents): keep watch supervisor retrying

4a30f30

fix(agents): use refreshed Codex credential aliases

6c3ded0

fix(gator): avoid misleading gh auth checks

8b49cc2

docs(agents): remove architecture build update

2215eb2

fix(gator): use REST-backed GitHub writes

0b8790a

fix(agents): bake immutable agent payloads

293b9e2

johntmyers and others added 15 commits June 26, 2026 12:23

fix(agents): upload writable agent workspace

2ca2520

fix(agents): surface gator watch progress

aee601c

fix(agents): prevent codex stdin hang

eb925e0

fix(agents): align codex subagent input

14cdeff

fix(agents): heartbeat during active cycles

ef48e39

fix(agents): clean up heartbeat sleep

882b070

fix(agents): disable gh telemetry in codex harness

acc9c9f

fix(agents): reconcile closed gator PRs

3f81f6e

fix(agents): query closed gator PR labels separately

4e2f9f9

fix(agents): tolerate rotated credential placeholders

5827f36

fix(agents): enforce gator same-sha comment guard

005b8b9

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

docs(agents): scope gator trusted commentary

859e290

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

fix(gator): treat reviewer failures as transient

de4a121

Signed-off-by: Evan Lezar <elezar@nvidia.com>

feat(agents): refine gator supervised workflow

db673cc

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

fix(agents): stream codex prompts via stdin

cc78ee2

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers force-pushed the feat/gator-gate-skill branch from fec9f3e to cc78ee2 Compare June 26, 2026 19:29

docs(agents): clarify trusted gator responses

5c9c10b

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

elezar reviewed Jun 29, 2026

View reviewed changes

refactor(agents): scope gator PR to scripts

b7da77f

Signed-off-by: John Myers <johntmyers@users.noreply.github.com>

johntmyers mentioned this pull request Jun 29, 2026

fix(providers): reserve credential placeholder revisions #2049

Merged

9 tasks

drew approved these changes Jun 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(agents): add manifest-driven gator agent#1826

feat(agents): add manifest-driven gator agent#1826
johntmyers wants to merge 36 commits into
mainfrom
feat/gator-gate-skill

johntmyers commented Jun 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

elezar commented Jun 10, 2026

Uh oh!

copy-pr-bot Bot commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026

Uh oh!

Uh oh!

johntmyers commented Jun 26, 2026

Uh oh!

elezar Jun 29, 2026

Uh oh!

elezar Jun 29, 2026

Uh oh!

elezar left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

johntmyers commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

Uh oh!

Uh oh!

elezar commented Jun 10, 2026

Uh oh!

copy-pr-bot Bot commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026

Uh oh!

Uh oh!

johntmyers commented Jun 26, 2026

Uh oh!

elezar Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

johntmyers commented Jun 9, 2026 •

edited

Loading