Extract a reusable Generic Agent from amber-review's sandbox orchestration pattern

[markturansky]

Summary

amber-review is a fully working CronJob-based agent that consumes OpenShell sandboxes to run AI code reviews on pull requests. The orchestration layer it uses — gateway authentication, sandbox lifecycle management, policy enforcement, provider injection, script upload/execution, and cleanup — is entirely general-purpose and not specific to code review.

Other teams have already asked how to build their own sandbox-consuming agents (different workloads, same infrastructure). Today the answer is "read amber-review's 600+ lines of bash and replicate the parts you need." That's fragile, hard to maintain across consumers, and buries the conceptual simplicity of the pattern under one use case's specifics.

This issue proposes extracting the reusable orchestration into a Generic Agent base that others can build on top of.

What's general vs. what's amber-specific

General (extract into reusable base)

• Gateway authentication lifecycle: gateway add → gateway login → periodic token refresh (the renew_gateway_login loop with configurable refresh interval)
• Sandbox lifecycle: create with --keep → poll for ready (ready-file probe) → exec → delete, with timeout handling and cleanup-on-exit traps
• Provider verification: pre-flight check that required providers exist in the workspace before creating sandboxes
• Stale sandbox cleanup: list sandboxes by label selector → delete leftovers from previous runs
• Policy file structure: the filesystem/network/process policy YAML schema and the pattern of having different policies for different sandbox roles
• Provider definition: the credential-bundle YAML schema for registering API access (endpoints, binaries, auth style)
• Init container for openshell CLI: download + SHA256 verify + install to shared volume
• CronJob skeleton: the Kubernetes manifest structure (init container, volume layout, security context, configMapGenerator pattern)
• Signal handling and cleanup: trap-based cleanup of child processes and sandbox resources on SIGINT/SIGTERM/EXIT
• Detached execution pattern: setsid --fork inside sandbox for long-running workloads that survive exec timeouts, with status-file polling from outside
• Isolated config roots: per-sandbox HOME/XDG_CONFIG_HOME/XDG_STATE_HOME so parallel sandboxes don't stomp each other's gateway state

Amber-specific (stays in amber-review)

• GitHub PR discovery logic (listing PRs, checking for existing reviews, idempotency markers)
• Claude Code invocation and retry logic
• Review verdict classification and status comment management
• The specific review prompt and cross-PR conflict analysis
• Repository-scoped GitHub provider endpoint rules

Proposed deliverable

A bases/agent (or similar) directory in hypershell-gitops containing:

1. Template CronJob manifest

A parameterized CronJob skeleton with the proven volume layout:

Volume	Mount	Purpose
runner	/opt/agent (ro)	Agent scripts via ConfigMap
policy	/etc/agent (ro)	Sandbox policy files via ConfigMap
tools	/tools	openshell binary (init → main)
work	/work	Sandbox config roots, intermediate state
tmp	/tmp	Scratch space

Init container pre-baked with the install-openshell.py pattern (version + per-arch SHA256 as env vars).

2. Library script (agent-lib.sh)

Extracted functions that any agent can source:

source /opt/agent/agent-lib.sh

# Gateway lifecycle
configure_gateway "$config_root"
renew_gateway_login "$config_root" [force]

# Sandbox lifecycle
create_sandbox "$config_root" "$sandbox_name" "$sandbox_source" \
  --provider "$PROVIDER_1" --policy /etc/agent/policy.yaml \
  --upload "./my-script.sh:/tmp/my-script.sh" \
  --label managed-by=my-agent
wait_for_sandbox "$config_root" "$sandbox_name" "$timeout"
exec_in_sandbox "$config_root" "$sandbox_name" "$timeout" [--env K=V]... -- command
delete_sandbox "$config_root" "$sandbox_name"

# Housekeeping
verify_providers "$config_root" provider1 provider2 ...
cleanup_stale_sandboxes "$config_root" "managed-by=my-agent"

3. Reference policy and provider templates

Documented, minimal-privilege examples:

• policy-template.yaml — annotated with what each section controls
• provider-template.yaml — annotated credential bundle skeleton

4. Kustomize base

A kustomization.yaml that downstream agents overlay with their own scripts, policies, env vars, and schedule — similar to how bases/hypershell/base works for control-plane instances.

5. Documentation

A concise README covering:

• Prerequisites (gateway endpoint, OIDC credentials, workspace, providers)
• The openshell CLI lifecycle (add → login → create → exec → delete)
• How to write a policy file (filesystem, network, process constraints)
• How to define and register a provider
• How to build a new agent on top of the base (kustomize overlay pattern)
• The detached-exec pattern for long-running workloads

Why this matters

• Reuse: Teams building new agents (CI bots, security scanners, test runners, data pipelines) get a working starting point instead of reverse-engineering amber-review
• Consistency: All agents use the same gateway auth, cleanup, and security patterns — fixes and improvements propagate via the shared base
• Security baseline: The policy/provider/NetworkPolicy patterns encode least-privilege defaults that are easy to get wrong when starting from scratch
• Maintainability: amber-review itself becomes a thin overlay on the generic base, reducing its own maintenance surface

Migration path for amber-review

Once the generic base exists, amber-review would become a kustomize overlay that adds:

• discover.sh, review.sh (amber-specific scripts)
• amber-github-provider.yaml (scoped GitHub access)
• Review-specific env vars (REPOSITORY, CLAUDE_MODEL, etc.)
• Its own run.sh that sources agent-lib.sh and calls the discovery/review phases

This is a refactor, not a rewrite — the proven amber-review logic stays intact, it just delegates the generic orchestration to the shared library.

Scope notes

• This does not propose changes to the openshell CLI or gateway itself — it's purely about the consumption pattern on the Kubernetes/gitops side
• Provider registration in the workspace is still a manual/API step — this issue covers the gitops manifests and scripts, not gateway-side automation
• The install-openshell.py init container pattern pins a specific CLI version with SHA256 verification — this is intentional and should be preserved, not replaced with "latest"

[markturansky]

Triage — Robert (build agent)

Type: kind/feature — proposes extracting amber-review's sandbox orchestration (gateway auth, sandbox lifecycle, policy, cleanup) into a reusable Generic Agent base for other sandbox-consuming agents.

Severity: priority/important-longterm — teams are already asking how to build their own agents; the current path is reverse-engineering amber-review's 600+ lines of bash.

Duplicates/Related: PR #274 (feat(agents): generic agent base and agent-example reference overlay [HYPERSHELL-273]) is the open implementation PR for this issue. Not a duplicate — it's the active work item.

Missing information: None — the issue provides a comprehensive spec covering what to extract, the deliverable structure (bases/agent, agent-lib.sh, templates, kustomize base), and the migration path for amber-review.

Next action: Review and merge PR #274, which directly implements this specification.

[hypershell-builder]

Robert is working this issue — spec-change PR incoming.

[hypershell-builder]

Spec-change PR opened: #330 — pending human review. Once merged, reconcile will implement the code.

Note: this sandbox's API proxy denies DELETE and PUT on the issue-labels endpoint, so I could not remove robert/available or robert/in-progress automatically. A human should drop those two so only robert/spec-drafted remains set.