diff --git a/.agents/agents/README.md b/.agents/agents/README.md new file mode 100644 index 0000000000..c98f9b62b7 --- /dev/null +++ b/.agents/agents/README.md @@ -0,0 +1,107 @@ +# Agents + +Agents live in `.agents/agents//`. Names are descriptive nouns specifying the job, optionally qualified by adjectives: `labeler`, `reviewer`, or `security-reviewer`. + +## Layout + +```text +.agents/ +|-- skills/ +| `-- agent-behavior -> ../agents/agent-name/skills/agent-behavior +`-- agents/ + |-- README.md + `-- agent-name/ + |-- README.md + |-- run.py + |-- bin/ + | |-- helper.py + | `-- tool.py + |-- prompts/ + | `-- task.md + |-- skills/ + | `-- agent-behavior/ + | `-- SKILL.md + |-- references/ + | `-- result-contract.md + |-- tests/ + | |-- run_test.py + | `-- tool_test.py + |-- deploy/ + | |-- Dockerfile + | `-- policy.yaml + `-- evals/ + `-- cases.json +``` + +Only `README.md` and a `run.*` entry point are required. Add other directories when needed; do not create empty scaffolding. + +- `run.*` is the agent-root entry point for humans, workflows, and interactive callers. Use the implementation language's extension, such as `run.py` or `run.sh`. It can delegate to a shared launcher. +- `bin/` holds supporting scripts, tools, and implementation modules. +- `prompts/` holds model or harness prompts. +- `skills/` holds canonical agent-owned skills. A symlink in [`.agents/skills/`](../skills) can expose the same skill for discovery. Reference canonical instructions and contracts rather than copying them. +- `references/` holds contracts and supporting guidance. +- `tests/` holds explicitly selected deterministic and integration tests. +- `evals/` holds model-quality cases and scoring code. +- `deploy/` holds execution-specific packaging assets, such as a Dockerfile and sandbox policy. Manifests and dependency files live at the agent root where their tooling expects them. Never commit secrets. +- `README.md` covers setup, invocation, permissions, outputs, and recovery. + +## Deterministic orchestration + +The `labeler` agent checks authorization, acceptance, lifecycle, and material changes before calling a model-based classifier. The classifier receives prepared evidence and no tools; deterministic code validates and applies the result. + +```text +labeler/ +|-- README.md +|-- run.py +|-- bin/ +| |-- acceptance.py +| |-- classifier.py +| |-- evidence.py +| `-- policy.py +|-- prompts/ +| `-- classify.md +|-- skills/ +| `-- label-issue/ +| |-- SKILL.md +| `-- references/ +| `-- result-contract.md +`-- tests/ + |-- run_test.py + |-- acceptance_test.py + |-- classifier_test.py + |-- evidence_test.py + `-- policy_test.py +``` + +Execution: `run.py` -> deterministic gates -> prepared evidence -> model-based classifier -> validation and application. Deterministic skips create no model session. Acceptance recognizes established policy and human disposition; the model does not accept work. + +## Harness-driven execution + +A reviewer launches a model/harness with a prompt and selected tools. Its entry point enforces invocation scope and permissions; sandbox policy, guarded commands, or SDK tool handlers enforce tool access. + +```text +reviewer/ +|-- README.md +|-- run.sh +|-- agent.yaml +|-- bin/ +| |-- read-item +| `-- submit-findings +|-- prompts/ +| `-- review.md +|-- skills/ +| `-- review-item/ +| `-- SKILL.md +|-- references/ +| `-- result-contract.md +|-- deploy/ +| |-- Dockerfile +| `-- policy.yaml +`-- tests/ + |-- run_test.sh + `-- submit_findings_test.sh +``` + +Execution: `run.sh` -> scope checks -> harness with prompt and tools -> validated result. Tools can be registered SDK functions or guarded sandbox commands. Supervision and repeated cycles belong outside the model. + +These examples illustrate execution styles, not an inventory of agents. diff --git a/scripts/agents/gator/.gitignore b/.agents/agents/gator/.gitignore similarity index 100% rename from scripts/agents/gator/.gitignore rename to .agents/agents/gator/.gitignore diff --git a/scripts/agents/gator/Dockerfile b/.agents/agents/gator/Dockerfile similarity index 100% rename from scripts/agents/gator/Dockerfile rename to .agents/agents/gator/Dockerfile diff --git a/scripts/agents/gator/README.md b/.agents/agents/gator/README.md similarity index 91% rename from scripts/agents/gator/README.md rename to .agents/agents/gator/README.md index f96c7a1a8a..ff1d433a7e 100644 --- a/scripts/agents/gator/README.md +++ b/.agents/agents/gator/README.md @@ -2,6 +2,8 @@ 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. +The agent-root entry point is `.agents/agents/gator/run.sh`. + ## Prerequisites - `gh` is authenticated on the host and has access to `NVIDIA/OpenShell`. @@ -13,14 +15,13 @@ Launch a headless sandbox agent that runs the `gator-gate` skill against OpenShe ## Usage ```shell -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --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 image source. It builds `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 a task-independent prompt template, skills, subagents, and shared runtime files into `/etc/openshell/agent-payload`, then passes the resulting image reference to `openshell sandbox create`. +By default the launcher uses `.agents/agents/gator/Dockerfile` as the sandbox image source. It builds `.agents/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 a task-independent prompt template, skills, subagents, and shared runtime files into `/etc/openshell/agent-payload`, then passes the resulting image reference to `openshell sandbox create`. The PR assignment, operator test authorization, harness selection, watch mode, and polling interval are runtime inputs, not rendered image contents. The launcher supplies the non-secret assignment as `OPENSHELL_AGENT_TASK` in the canonical process command. The supervisor assembles the prompt once in memory and sends it to each harness cycle on stdin; cycles do not read task instructions from an agent-writable file. Assignment text is literal data, so shell syntax and template tokens inside it are not evaluated. Do not put credentials in assignments; use providers. Runtime command metadata can contain the assignment. This separates reusable tooling from per-run instructions; it does not make prompt instructions a security boundary. @@ -41,8 +42,8 @@ requires the matching current kube context and a running local cluster, builds with Docker, and imports the image into that cluster before creating a sandbox: ```shell -OPENSHELL_WORKSPACE=gator mise exec k3d@5.9.0 -- ./scripts/agents/run.sh \ - --agent gator --gateway openshell-dev-main \ +OPENSHELL_WORKSPACE=gator mise exec k3d@5.9.0 -- ./.agents/agents/gator/run.sh \ + --gateway openshell-dev-main \ --k3d-cluster openshell-dev-main --name gtr-pr-1234 --watch \ "Review and monitor PR #1234 through the gator-gate workflow." ``` @@ -57,8 +58,8 @@ changing gateway settings, importing providers, reading provider credentials, or launching a sandbox: ```shell -./scripts/agents/run.sh --agent gator --gateway remote-kube \ - --publish-image registry.example.com/team/gator:payload-13 --build-only +./.agents/agents/gator/run.sh --gateway remote-kube \ + --publish-image registry.example.com/team/gator:payload-14 --build-only ``` The builder uses existing Docker/Podman registry authentication. Both local and @@ -71,8 +72,8 @@ The launcher prints `Tooling image: REGISTRY/REPOSITORY@sha256:DIGEST` after a successful push. Reuse that full reference for subsequent tasks: ```shell -OPENSHELL_WORKSPACE=gator ./scripts/agents/run.sh \ - --agent gator --gateway remote-kube --name gtr-pr-1234 --watch \ +OPENSHELL_WORKSPACE=gator ./.agents/agents/gator/run.sh \ + --gateway remote-kube --name gtr-pr-1234 --watch \ --image "$GATOR_IMAGE" \ "Review and monitor PR #1234 through the gator-gate workflow." ``` @@ -122,7 +123,7 @@ The launcher: Gator-owned GitHub review thread without touching human review threads. - Installs `gator/bin/validate-review-findings` to downgrade blockers that lack the required reachability, ownership, base-vs-head, impact, and reproducer evidence. - Keeps that normalized evidence as Gator's internal review contract, then renders validated blockers for people as a read-aloud `Summary`, an actionable `Fix`, and a deterministic `Verify`. Exact paths and only the additional provenance an implementation agent needs appear in collapsed `Agent context`; raw evidence headings such as `Base` and `Head` are not posted publicly. Review-process provenance, docs and E2E disposition, SHAs, and state codes appear at the end of the summary in collapsed `Gator metadata`, while required human actions remain visible. -- Bakes `scripts/agents/gator/skills/gator-gate/SKILL.md` into `/etc/openshell/agent-payload`. +- Bakes `.agents/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. @@ -138,13 +139,8 @@ The launcher preserves existing gateway-owned Codex refresh material by default ## Tests +The test suite requires Bash, Ruby, Node.js, jq, and ripgrep on the host. It mocks image, gateway, credential, and GitHub operations. + ```shell -bash scripts/agents/gator/bin/gh_guard_test.sh -bash scripts/agents/gator/bin/review_feedback_ledger_test.sh -bash scripts/agents/gator/bin/resolve_gator_review_threads_test.sh -bash scripts/agents/runtime/harnesses/codex/exec_test.sh -bash scripts/agents/run_test.sh -bash scripts/agents/image_test.sh -bash scripts/agents/runtime/launch_test.sh -bash scripts/agents/runtime/supervisor_test.sh +mise run test:gator ``` diff --git a/scripts/agents/gator/agent.yaml b/.agents/agents/gator/agent.yaml similarity index 99% rename from scripts/agents/gator/agent.yaml rename to .agents/agents/gator/agent.yaml index 7a4128a05d..5e19db707a 100644 --- a/scripts/agents/gator/agent.yaml +++ b/.agents/agents/gator/agent.yaml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 id: gator -payload_version: 13 +payload_version: 14 display_name: Gator Gate Agent description: Validate and monitor OpenShell GitHub issues and pull requests through the gator state machine. diff --git a/scripts/agents/gator/bin/gh b/.agents/agents/gator/bin/gh similarity index 100% rename from scripts/agents/gator/bin/gh rename to .agents/agents/gator/bin/gh diff --git a/scripts/agents/gator/bin/resolve-gator-review-threads b/.agents/agents/gator/bin/resolve-gator-review-threads similarity index 100% rename from scripts/agents/gator/bin/resolve-gator-review-threads rename to .agents/agents/gator/bin/resolve-gator-review-threads diff --git a/scripts/agents/gator/bin/review-feedback-ledger b/.agents/agents/gator/bin/review-feedback-ledger similarity index 100% rename from scripts/agents/gator/bin/review-feedback-ledger rename to .agents/agents/gator/bin/review-feedback-ledger diff --git a/scripts/agents/gator/bin/validate-review-findings b/.agents/agents/gator/bin/validate-review-findings similarity index 100% rename from scripts/agents/gator/bin/validate-review-findings rename to .agents/agents/gator/bin/validate-review-findings diff --git a/scripts/agents/gator/policy.yaml b/.agents/agents/gator/policy.yaml similarity index 100% rename from scripts/agents/gator/policy.yaml rename to .agents/agents/gator/policy.yaml diff --git a/scripts/agents/gator/prompts/gator.md b/.agents/agents/gator/prompts/gator.md similarity index 99% rename from scripts/agents/gator/prompts/gator.md rename to .agents/agents/gator/prompts/gator.md index d4c707b3db..1b8629153a 100644 --- a/scripts/agents/gator/prompts/gator.md +++ b/.agents/agents/gator/prompts/gator.md @@ -17,7 +17,7 @@ Important sandbox constraints: actions and use GraphQL-backed `gh` reads when useful. - Keep watching active PRs until they close, merge, or the operator stops the sandbox. - At the start of every watch cycle, read `payload_version` from - `scripts/agents/gator/agent.yaml` on the default branch through the GitHub + `.agents/agents/gator/agent.yaml` on the default branch through the GitHub contents API. If the published integer is greater than `{{PAYLOAD_VERSION}}`, do not write to GitHub or run the reviewer. Finish with `OPENSHELL_AGENT_RESULT {"status":"terminal_failure","reason":"stale_gator_payload","notes":"This sandbox is using an outdated Gator payload. Relaunch it before monitoring continues."}` so the operator relaunches the immutable watcher. diff --git a/scripts/agents/gator/providers/codex-gator.yaml b/.agents/agents/gator/providers/codex-gator.yaml similarity index 100% rename from scripts/agents/gator/providers/codex-gator.yaml rename to .agents/agents/gator/providers/codex-gator.yaml diff --git a/scripts/agents/gator/providers/github-gator.yaml b/.agents/agents/gator/providers/github-gator.yaml similarity index 100% rename from scripts/agents/gator/providers/github-gator.yaml rename to .agents/agents/gator/providers/github-gator.yaml diff --git a/.agents/agents/gator/run.sh b/.agents/agents/gator/run.sh new file mode 100755 index 0000000000..3fca9e9e82 --- /dev/null +++ b/.agents/agents/gator/run.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash + +set -euo pipefail + +AGENT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(cd "$AGENT_DIR/../../.." && pwd)" + +exec bash "$ROOT_DIR/scripts/agents/run.sh" --agent "$AGENT_DIR" "$@" diff --git a/scripts/agents/gator/skills/gator-gate/SKILL.md b/.agents/agents/gator/skills/gator-gate/SKILL.md similarity index 99% rename from scripts/agents/gator/skills/gator-gate/SKILL.md rename to .agents/agents/gator/skills/gator-gate/SKILL.md index 99c6b711de..233ba9c9f0 100644 --- a/scripts/agents/gator/skills/gator-gate/SKILL.md +++ b/.agents/agents/gator/skills/gator-gate/SKILL.md @@ -11,7 +11,7 @@ This skill is a gating workflow. It can start from any issue or PR state, inspec ## Skill Location -Codex and other agent harnesses should load this skill from the repository path `scripts/agents/gator/skills/gator-gate/SKILL.md`. After this branch is merged, the canonical GitHub location is . +Codex and other agent harnesses should load this skill from the repository path `.agents/agents/gator/skills/gator-gate/SKILL.md`. After this branch is merged, the canonical GitHub location is . ## Prerequisites @@ -796,7 +796,7 @@ Use the `principal-engineer-reviewer` sub-agent. Include: `LEFT` for a deleted line), severity, finding ID, and concise comment body - Instruction not to rely on local test execution -When running inside the `scripts/agents/gator` sandbox launcher, invoke the reviewer command specified in the sandbox prompt. Use `task.md` for the subagent input. Put the review feedback ledger, review mode, PR metadata, linked issue context, and mode-appropriate diff/file context in `task.md`. Require the reviewer to emit only the JSON envelope described in `references/review-findings-schema.md` to `review-findings.raw.json`, then run `validate-review-findings review-findings.raw.json > review-findings.json`. Only normalized entries with `blocking: true` may affect labels or public review comments. Missing evidence downgrades a proposed Critical or Warning to a non-blocking hypothesis; do not repair the reviewer output by guessing. The main gator process remains responsible for labels, comments, docs gates, and CI monitoring. Before posting, compare every proposed finding with all open, resolved, and waived ledger findings plus prior review summaries. Remove semantically equivalent findings unless the new diff reintroduces the defect or newly available evidence meets the Critical unchanged-code exception above. If the reviewer command exits nonzero or the saved reviewer output is absent, malformed, or fails envelope validation, stop the cycle with the `reviewer_subagent_failed` transient result described above without changing GitHub labels or posting a public disposition. +When running inside the `.agents/agents/gator` sandbox launcher, invoke the reviewer command specified in the sandbox prompt. Use `task.md` for the subagent input. Put the review feedback ledger, review mode, PR metadata, linked issue context, and mode-appropriate diff/file context in `task.md`. Require the reviewer to emit only the JSON envelope described in `references/review-findings-schema.md` to `review-findings.raw.json`, then run `validate-review-findings review-findings.raw.json > review-findings.json`. Only normalized entries with `blocking: true` may affect labels or public review comments. Missing evidence downgrades a proposed Critical or Warning to a non-blocking hypothesis; do not repair the reviewer output by guessing. The main gator process remains responsible for labels, comments, docs gates, and CI monitoring. Before posting, compare every proposed finding with all open, resolved, and waived ledger findings plus prior review summaries. Remove semantically equivalent findings unless the new diff reintroduces the defect or newly available evidence meets the Critical unchanged-code exception above. If the reviewer command exits nonzero or the saved reviewer output is absent, malformed, or fails envelope validation, stop the cycle with the `reviewer_subagent_failed` transient result described above without changing GitHub labels or posting a public disposition. Post findings using these rules: diff --git a/scripts/agents/gator/skills/gator-gate/references/review-findings-schema.md b/.agents/agents/gator/skills/gator-gate/references/review-findings-schema.md similarity index 100% rename from scripts/agents/gator/skills/gator-gate/references/review-findings-schema.md rename to .agents/agents/gator/skills/gator-gate/references/review-findings-schema.md diff --git a/scripts/agents/gator/bin/gh_guard_test.sh b/.agents/agents/gator/tests/gh_guard_test.sh similarity index 98% rename from scripts/agents/gator/bin/gh_guard_test.sh rename to .agents/agents/gator/tests/gh_guard_test.sh index c1571866c1..0d4555ed15 100755 --- a/scripts/agents/gator/bin/gh_guard_test.sh +++ b/.agents/agents/gator/tests/gh_guard_test.sh @@ -5,7 +5,8 @@ set -euo pipefail -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +GATOR_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SCRIPT_DIR="$GATOR_DIR/bin" WRAPPER="$SCRIPT_DIR/gh" assert_status() { diff --git a/scripts/agents/gator/bin/resolve_gator_review_threads_test.sh b/.agents/agents/gator/tests/resolve_gator_review_threads_test.sh similarity index 96% rename from scripts/agents/gator/bin/resolve_gator_review_threads_test.sh rename to .agents/agents/gator/tests/resolve_gator_review_threads_test.sh index 1e38947d9a..6529342e49 100755 --- a/scripts/agents/gator/bin/resolve_gator_review_threads_test.sh +++ b/.agents/agents/gator/tests/resolve_gator_review_threads_test.sh @@ -5,8 +5,8 @@ set -euo pipefail -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GATOR_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +GATOR_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SCRIPT_DIR="$GATOR_DIR/bin" RESOLVER="$SCRIPT_DIR/resolve-gator-review-threads" tmp="$(mktemp -d)" diff --git a/scripts/agents/gator/bin/review_feedback_ledger_test.sh b/.agents/agents/gator/tests/review_feedback_ledger_test.sh similarity index 97% rename from scripts/agents/gator/bin/review_feedback_ledger_test.sh rename to .agents/agents/gator/tests/review_feedback_ledger_test.sh index e222bd329a..b80aad6b9e 100755 --- a/scripts/agents/gator/bin/review_feedback_ledger_test.sh +++ b/.agents/agents/gator/tests/review_feedback_ledger_test.sh @@ -5,8 +5,9 @@ set -euo pipefail -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GATOR_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +GATOR_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SCRIPT_DIR="$GATOR_DIR/bin" +ROOT_DIR="$(cd "$GATOR_DIR/../../.." && pwd)" LEDGER="$SCRIPT_DIR/review-feedback-ledger" tmp="$(mktemp -d)" @@ -406,14 +407,14 @@ rg -q 'COPY bin/validate-review-findings /usr/local/bin/validate-review-findings "$GATOR_DIR/Dockerfile" ruby -ryaml -e ' manifest = YAML.load_file(ARGV.fetch(0)) - abort unless manifest.fetch("payload_version") == 13 + abort unless manifest.fetch("payload_version") == 14 resource = manifest.fetch("resources").find { |entry| entry.fetch("id") == "gator-review-findings-schema" } abort unless resource.fetch("destination") == "skills/gator-gate/references/review-findings-schema.md" ' "$GATOR_DIR/agent.yaml" -rg -Fq 'manifest.fetch("resources", [])' "$GATOR_DIR/../run.sh" +rg -Fq 'manifest.fetch("resources", [])' "$ROOT_DIR/scripts/agents/run.sh" rg -Fq 'Gator payload version: {{PAYLOAD_VERSION}}' \ "$GATOR_DIR/prompts/gator.md" rg -q 'review-feedback-ledger NVIDIA OpenShell ' \ @@ -428,7 +429,7 @@ rg -Fq 'private_security_review_required' "$GATOR_DIR/skills/gator-gate/SKILL.md rg -Fq 'Do not initiate external disclosure' "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -Fq 'not a generic private-security blocker' "$GATOR_DIR/prompts/gator.md" rg -Fq 'Security classification alone is not a private-triage gate' \ - "$GATOR_DIR/../../../.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" rg -q '### Pragmatic review calibration' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'A new commit permits a delta review' \ @@ -440,9 +441,9 @@ rg -q 'available evidence demonstrates a Critical' \ rg -q 'Keep reviews pragmatic and convergent' \ "$GATOR_DIR/prompts/gator.md" rg -q '### Pragmatic review calibration' \ - "$GATOR_DIR/../../../.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" rg -q 'Do not mine unchanged code for new findings' \ - "$GATOR_DIR/../../../.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" rg -q 'three finding-bearing rounds' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'alone is not a process blocker' \ @@ -452,7 +453,7 @@ rg -q '`test_dispatch_required`' \ rg -q 'Apply `test:windows` whenever a PR affects Windows support' \ "$GATOR_DIR/skills/gator-gate/SKILL.md" rg -q 'require the `test:windows` label' \ - "$GATOR_DIR/../../../.claude/agents/principal-engineer-reviewer.md" + "$ROOT_DIR/.claude/agents/principal-engineer-reviewer.md" rg -q 'attacker_or_operator_prerequisite' \ "$GATOR_DIR/skills/gator-gate/references/review-findings-schema.md" rg -Fq 'Write `Summary` as natural prose that can be read aloud' \ diff --git a/scripts/agents/gator/bin/validate_review_findings_test.sh b/.agents/agents/gator/tests/validate_review_findings_test.sh similarity index 97% rename from scripts/agents/gator/bin/validate_review_findings_test.sh rename to .agents/agents/gator/tests/validate_review_findings_test.sh index 853b9f2280..161fd0c6fb 100755 --- a/scripts/agents/gator/bin/validate_review_findings_test.sh +++ b/.agents/agents/gator/tests/validate_review_findings_test.sh @@ -5,7 +5,8 @@ set -euo pipefail -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +GATOR_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SCRIPT_DIR="$GATOR_DIR/bin" VALIDATOR="$SCRIPT_DIR/validate-review-findings" tmp="$(mktemp -d)" trap 'rm -rf "$tmp"' EXIT diff --git a/.agents/skills/launch-openshell-gator/SKILL.md b/.agents/skills/launch-openshell-gator/SKILL.md index 9fba2b89e2..dc5e5b2e4a 100644 --- a/.agents/skills/launch-openshell-gator/SKILL.md +++ b/.agents/skills/launch-openshell-gator/SKILL.md @@ -7,7 +7,7 @@ metadata: # Launch OpenShell Gator -Launch and supervise the repository's headless gator sandbox agent through OpenShell. This skill covers the operator workflow around `scripts/agents/run.sh`; the in-sandbox review and state-machine policy remains the `gator-gate` skill baked into the gator payload. +Launch and supervise the repository's headless gator sandbox agent through OpenShell. This skill covers the operator workflow around `.agents/agents/gator/run.sh`; the in-sandbox review and state-machine policy remains the `gator-gate` skill baked into the gator payload. For gator's PR/issue validation policy, load `gator-gate` inside the launched sandbox. For generic sandbox CLI usage, use `openshell-cli`. For unhealthy gateways or sandbox startup failures, use `debug-openshell-cluster` after the launch preflight identifies a gateway/runtime problem. @@ -15,7 +15,7 @@ For gator's PR/issue validation policy, load `gator-gate` inside the launched sa - Keep normal gator launches supervised: use `--watch` and let the in-sandbox supervisor own sleeping and relaunching bounded cycles. - Do not add passive `sleep` loops in the operator session to watch gator. Check logs or status once, then report the current state or launch a proper watcher outside the model session only when explicitly asked. -- Do not change the default gator model in `scripts/agents/gator/agent.yaml` for experiments. Use `CODEX_MODEL=...` and, if needed, a temporary `--from` Docker context or `--codex-bin` override. +- Do not change the default gator model in `.agents/agents/gator/agent.yaml` for experiments. Use `CODEX_MODEL=...` and, if needed, a temporary `--from` Docker context or `--codex-bin` override. - Do not push to contributor branches, approve, merge, post `/ok to test`, or broaden gator scope unless the operator explicitly authorized that action. - Scope each launch prompt to the requested issue/PR set. Avoid repo-wide gator scans unless the operator asked for repo-wide processing. - Leave unrelated local files alone, including `.opencode/` artifacts and old gator logs unless the user asks for cleanup. @@ -24,16 +24,16 @@ For gator's PR/issue validation policy, load `gator-gate` inside the launched sa | Path | Purpose | |---|---| -| `scripts/agents/run.sh` | Manifest-driven OpenShell agent launcher. | -| `scripts/agents/gator/agent.yaml` | Gator manifest: immutable payload version, default gateway, harness, providers, runtime, skills, and subagents. | -| `scripts/agents/gator/Dockerfile` | Gator sandbox image source. Local launches build it in gateway's Docker or Podman image store. | -| `scripts/agents/gator/policy.yaml` | Sandbox policy for the gator agent. | -| `scripts/agents/gator/bin/gh` | Gator-specific `gh` wrapper and same-SHA duplicate-post guard. | -| `scripts/agents/gator/bin/review-feedback-ledger` | Builds tree-aware review scope, durable findings, convergence telemetry, and review-budget state. | -| `scripts/agents/gator/bin/resolve-gator-review-threads` | Resolves addressed Gator-owned inline review threads by ledger finding ID. | -| `scripts/agents/gator/bin/validate-review-findings` | Enforces the blocker evidence schema and downgrades unsupported hypotheses. | -| `scripts/agents/gator/prompts/gator.md` | Rendered top-level prompt template baked into the payload. | -| `scripts/agents/gator/skills/gator-gate/SKILL.md` | In-sandbox gator state-machine skill. | +| `.agents/agents/gator/run.sh` | Manifest-driven OpenShell agent launcher. | +| `.agents/agents/gator/agent.yaml` | Gator manifest: immutable payload version, default gateway, harness, providers, runtime, skills, and subagents. | +| `.agents/agents/gator/Dockerfile` | Gator sandbox image source. Local launches build it in gateway's Docker or Podman image store. | +| `.agents/agents/gator/policy.yaml` | Sandbox policy for the gator agent. | +| `.agents/agents/gator/bin/gh` | Gator-specific `gh` wrapper and same-SHA duplicate-post guard. | +| `.agents/agents/gator/bin/review-feedback-ledger` | Builds tree-aware review scope, durable findings, convergence telemetry, and review-budget state. | +| `.agents/agents/gator/bin/resolve-gator-review-threads` | Resolves addressed Gator-owned inline review threads by ledger finding ID. | +| `.agents/agents/gator/bin/validate-review-findings` | Enforces the blocker evidence schema and downgrades unsupported hypotheses. | +| `.agents/agents/gator/prompts/gator.md` | Rendered top-level prompt template baked into the payload. | +| `.agents/agents/gator/skills/gator-gate/SKILL.md` | In-sandbox gator state-machine skill. | ## Preflight @@ -96,7 +96,7 @@ nodes need their own pull access. `--build-only` builds/delivers without gateway mutations, provider credential reads, or a sandbox launch. Reused images must match the local manifest's agent ID and payload version and support the runtime task contract; legacy baked-task images fail startup. See -`scripts/agents/gator/README.md` for examples and option compatibility. +`.agents/agents/gator/README.md` for examples and option compatibility. ### Step 5: Verify Gateway Is Registered And Alive @@ -171,8 +171,7 @@ pr_number="" sandbox_name="gtr-pr-${pr_number}-watch" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ @@ -193,8 +192,7 @@ issue_number="" sandbox_name="gtr-i-${issue_number}-watch" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ @@ -213,8 +211,7 @@ issue_number="" sandbox_name="gtr-pr-${pr_number}-watch" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ @@ -233,8 +230,7 @@ pr_number="" sandbox_name="gtr-pr-${pr_number}-watch" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ @@ -254,15 +250,14 @@ sandbox_name="gtr-pr-${pr_number}-exp" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } CODEX_MODEL=gpt-5.6-sol \ -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ "Review and monitor PR #${pr_number} through the gator-gate workflow. Scope this invocation only to PR #${pr_number}. This launch is intentionally testing Codex model gpt-5.6-sol via the CLI launcher." ``` -If the installed Codex CLI is too old for a model, create a temporary copy of `scripts/agents/gator/`, adjust only that temporary Dockerfile, and launch with that generated context. Keep the repo Dockerfile unchanged unless the version bump is the intended code change. +If the installed Codex CLI is too old for a model, create a temporary copy of `.agents/agents/gator/`, adjust only that temporary Dockerfile, and launch with that generated context. Keep the repo Dockerfile unchanged unless the version bump is the intended code change. The short `-exp` suffix below identifies an experimental watcher; keep its full name within 19 characters. @@ -276,11 +271,10 @@ pr_number="" sandbox_name="gtr-pr-${pr_number}-exp" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } tmp_context="$(mktemp -d "${TMPDIR:-/tmp}/gator-codex-XXXXXX")" -cp -R scripts/agents/gator/. "$tmp_context"/ +cp -R .agents/agents/gator/. "$tmp_context"/ CODEX_MODEL=gpt-5.6-sol \ -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --from "$tmp_context" \ @@ -346,7 +340,7 @@ transport diagnostics. Restart when the payload must change, the sandbox is wedged without a sentinel, the model/tooling version changed, or a transient failure repeats past the useful retry point. -Increment `payload_version` in `scripts/agents/gator/agent.yaml` whenever a +Increment `payload_version` in `.agents/agents/gator/agent.yaml` whenever a merged change alters the Gator prompt, gate skill, reviewer contract, write guard, ledger, thread resolver, or bundled validator. Existing immutable watchers cannot replace their own payload. New-version watchers detect later @@ -362,8 +356,7 @@ sandbox_name="" [[ "$sandbox_name" =~ ^[a-z0-9]([a-z0-9-]{0,17}[a-z0-9])?$ ]] || { echo "invalid sandbox name" >&2; exit 1; } openshell --gateway "$gateway_name" sandbox delete "$sandbox_name" -./scripts/agents/run.sh \ - --agent gator \ +./.agents/agents/gator/run.sh \ --gateway "$gateway_name" \ --name "$sandbox_name" \ --watch \ @@ -386,7 +379,7 @@ Symptoms: Dockerfile step failure, missing package, incompatible Codex CLI, regi Actions: -- Confirm the build context is `scripts/agents/gator/` or the intended temporary `--from` context. +- Confirm the build context is `.agents/agents/gator/` or the intended temporary `--from` context. - Confirm Docker or the selected gateway runtime can pull `nvcr.io/nvidia/base/ubuntu:noble-20251013`. - For Codex CLI version experiments, adjust a temporary Docker context first. - Do not commit Dockerfile version changes unless the repo should permanently use that version. diff --git a/AGENTS.md b/AGENTS.md index dfd769c7e2..57a12966cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,7 +73,7 @@ Do not rely on this file for a full inventory. The detailed public and contribut | `fern/` | Docs site config | Fern site config, components, and theme assets | | `skills/` | Public agent skills | Installable workflows for using and operating OpenShell | | `.agents/skills/` | Contributor agent skills | Repository-aware workflows for developing OpenShell | -| `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer) | +| `.agents/agents/` | Agents | Agent runtimes; see [layout](.agents/agents/README.md) | ## Public API Conventions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1bf50b4a4..d1b13d03c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -443,7 +443,7 @@ These are the primary `mise` tasks for day-to-day development: | `plans/` | Local plans (git-ignored) | | `rfc/` | Request for Comments proposals | | `skills/` | Public skills for using and operating OpenShell | -| `.agents/` | Contributor skills and persona definitions | +| `.agents/` | Contributor skills and [agents](.agents/agents/README.md) | ## RFCs diff --git a/scripts/agents/README.md b/scripts/agents/README.md index 176ee9df08..db853844be 100644 --- a/scripts/agents/README.md +++ b/scripts/agents/README.md @@ -5,6 +5,9 @@ manifest plus prompt assets that the shared launcher turns into an OpenShell sandbox run. Agents do not own harness implementations. Harness-specific setup and execution live in `runtime/harnesses//`. +Agent-specific bundles live in `.agents/agents//`; see the +[agent layout](../../.agents/agents/README.md). + ## Directory Layout ```text diff --git a/scripts/agents/run.sh b/scripts/agents/run.sh index a4525d791f..16bce25e11 100755 --- a/scripts/agents/run.sh +++ b/scripts/agents/run.sh @@ -34,7 +34,7 @@ usage() { cat <<'EOF' Options: - --agent NAME|PATH Agent manifest directory or name under scripts/agents/ + --agent NAME|PATH Agent manifest directory or name under .agents/agents/ --gateway NAME Gateway name to use --name NAME Sandbox name (DNS-1123 label, at most 19 characters) --from DOCKERFILE|DIR Local Dockerfile source for the sandbox image @@ -189,7 +189,7 @@ case "$AGENT_ARG" in AGENT_DIR="$AGENT_ARG" ;; *) - AGENT_DIR="$SCRIPT_DIR/$AGENT_ARG" + AGENT_DIR="$ROOT_DIR/.agents/agents/$AGENT_ARG" ;; esac diff --git a/tasks/test.toml b/tasks/test.toml index b2e599241c..147fa3ab83 100644 --- a/tasks/test.toml +++ b/tasks/test.toml @@ -31,6 +31,18 @@ depends = [ "test:label-issue", ] +["test:gator"] +description = "Test the Gator guarded tools and shared sandbox runtime" +run = [ + "for test in .agents/agents/gator/tests/*_test.sh; do bash \"$test\" || exit; done", + "bash scripts/agents/run_test.sh", + "bash scripts/agents/image_test.sh", + "bash scripts/agents/runtime/launch_test.sh", + "bash scripts/agents/runtime/supervisor_test.sh", + "bash scripts/agents/runtime/harnesses/codex/exec_test.sh", +] +hide = true + ["test:merge-gateway-toml"] description = "Test the tmachine gateway TOML merge script" run = "uv run --no-project --with pytest pytest tests/tmachine/ansible/roles/openshell_gateway/files/merge_gateway_toml_test.py"