reverse-engineering-anything/docs/specs/agent-environments/environment-export/spec.md

# Export an environment manifest as an agent environment bundle

Issue: https://github.com/morluto/rea/issues/4933

## Outcome

`rea environment-export <manifest.json> --evidence <capture.json> <dir>
[--package-tarball <path>] [--name <override>]` writes the manifest and
capture pair that `environment-serve` serves as a bundle folder the agentenv
framework runs with `agent-env run <dir>`: a README with provenance, an env
folder whose Dockerfile installs this exact `rea-agents` version and serves the
copied pair, a Python replay verifier and a smoke task. The hosted
`real-agentenv` lane exports such a bundle from the source-owned Grafana-shaped
capture through the built CLI, packs the checkout into the image and runs it
with the pinned framework release on the runner's Docker. This increment
completes the agent-environment work of the issue; serving came in the
previous increment.

## Requirements

- Read each of the two files once through the regular-file reader, parse it
  from those bytes and authenticate and cross-check the pair with
  `loadEnvironmentSource` as `environment-serve` does, so the bytes copied into
  the bundle are the bytes that were authenticated; every refusal reports
  operation `environment-export`, and a manifest projected from a different
  capture is refused before anything is written.
- Refuse a bundle directory that exists and is not empty, or that names a file,
  with an `invalid_request` whose issue path is `directory`; an absent or empty
  directory is accepted. Write every file with the exclusive-create flag so
  nothing is ever overwritten.
- Write `README.md`, `envs/<name>/Dockerfile`, `envs/<name>/env.toml`,
  `envs/<name>/manifest.json` and `envs/<name>/evidence.json` as byte-exact
  copies of the inputs (mode `0600` on POSIX; Windows retains inherited ACLs
  and does not provide an owner-only guarantee), `artifacts/check_<name>/verify.py` and
  `tasks/smoke.json`, where `<name>` defaults to the manifest's kebab-case name
  and `--name` must be a kebab-case label of at most 63 characters for its DNS label that is not a
  device name Windows reserves (`con`, `prn`, `aux`, `nul`, `com1`–`com9`,
  `lpt1`–`lpt9`). Its HTTP hostname identity must remain unchanged, so numeric
  labels interpreted as IP addresses are refused before planning.
- The Dockerfile uses the Node version pinned in `.nvmrc` with the
  `bookworm-slim` variant, sets
  `MCP_HOST=0.0.0.0`, `MCP_PORT=18765`, and
  `MCP_ALLOWED_HOSTS=127.0.0.1,localhost,<name>`, installs Debian's `python3` for the
  framework's readiness probe, installs
  `rea-agents@<PRODUCT_IDENTITY.packageVersion>` from the registry or, with
  `--package-tarball`, copies the tarball as `rea-agents.tgz`, installs it
  from `/tmp/` and removes it in the same layer, copies the pair to `/env/`,
  switches to the image's `node` user
  and runs `rea environment-serve /env/manifest.json --evidence
  /env/evidence.json`.
- `verify.py` mirrors the framework's echo example: `async def verify(mcp_url)`
  over `mcp.client.streamable_http`, lists the tools and checks the count
  equals the manifest's, calls the first `GET` tool without path parameters
  with no arguments and checks the replayed `status` equals the recorded status
  of that tool's first cited record, prints the description and returns
  `[{"id": "replay", "result": <bool>, "description": <both checks>}]`; with no
  such tool it checks the count only and says so.
- `tasks/smoke.json` is `deploy_env` of `<name>` on the local sandbox followed
  by `env_outcome_verifier` with `file_artifact_id` `check_<name>` and
  `verifier_id` `replay`. The README records the capture artifact SHA-256, both
  Evidence ids, the manifest view digest, the tool count and the package
  source, states what replay does and does not establish, names the run
  command as `agent-env run .` from the bundle root (the folder it sits in,
  whatever the caller named it), and carries the rights note.
- Print one JSON document with `status: "exported"`, the directory, name, tool
  count, both Evidence ids, the pinned `package_source` and the written files
  with sizes. Register the flat `environment-export` command in the CLI
  inventory; no MCP tool is added.
- Add the `agentenv` CI scope, the reusable `real-agentenv.yml` workflow
  (`workflow_dispatch` and `workflow_call` with `build_cache_artifact`,
  `ubuntu-24.04`, SHA-pinned actions, `setup-python` 3.12, a virtual
  environment with `agentenv-framework==0.9.1334`, the runner's Docker, 30
  minutes), the `verify:agentenv:environment` script and
  `scripts/verify-agentenv-environment.mjs`, which requires absolute
  `REA_AGENT_ENV_COMMAND` and `REA_DOCKER_COMMAND` like every other lane
  verifier, runs `agent-env run <dir> --sandbox local` bounded to 15 minutes
  and resolves nothing from `PATH`; wire `ci.yml` at the four spots and extend
  the two CI guard tests.

## Acceptance and limits

Services tests cover the planned file set, the Dockerfile for both package
sources, the verifier text, the smoke task, the README, the name override and
its refusals, writing into an absent and an empty directory with byte-exact
copies and correct sizes, the tarball copy, and the refusals of a non-empty
directory, a file path, a missing tarball and an inline manifest. The
conformance test pins the registry install to the `package.json` version. The
cli-boundary test writes the folder from the fixture pair through the built
CLI, refuses a non-empty directory leaving it unchanged, and refuses a
mismatched pair without creating the directory. The CI guard tests enumerate
the new consumer, route and classification cases. The local end-to-end run
recorded in `verification.md` is the proof that one exported bundle runs under
`agent-env run` with the smoke task passed and no container left behind.

The export copies bytes and never inspects the tarball; it does not build or
run the image itself. Its writes are not transactional: a host failure after
the first file leaves the partial folder for inspection, as `docs/cli.md`
states. The verifier checks one replayed status and the tool count, not every
tool. The lane passes `--sandbox local` as designed although
`tasks/smoke.json` already pins `sandbox_type: local` on its deploy step, so
the flag restates what the task fixes. The lane verifier imports the
Grafana-shaped HAR builder from `tests/fixtures/historicalHar.ts` through
Node's type stripping rather than carrying a second copy under `scripts/`; the
`agentenv` scope lists that fixture so a change to it runs the lane. The lane
proves one framework release on one hosted runner and claims nothing about
any hosted platform. Three additions to the
designed Dockerfile and file set were needed by the framework, each found by
the local run: `MCP_PORT=18765` as the listener default for the port the
framework maps, Debian's `python3` because the framework's local sandbox
probes readiness with `python3 -c "import socket; …"` inside the container and
the slim Node image has none, and `env.toml` naming the environment, because
the framework otherwise reads the name from Python sources the Node image does
not have.

## Deferred issue criteria

This increment closes the agent-environment scope of #4933 together with the
previous three. Running the lane on the maintainer's CI and any follow-up on
hosted platforms are outside this PR.