Skip to content

refactor(cli): ship one Eval runtime in the npm CLI package - #3946

Merged
Astro-Han merged 1 commit into
apache:mainfrom
liuxiaocs7:liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl
Aug 30, 2026
Merged

refactor(cli): ship one Eval runtime in the npm CLI package#3946
Astro-Han merged 1 commit into
apache:mainfrom
liuxiaocs7:liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl

Conversation

@liuxiaocs7

@liuxiaocs7 liuxiaocs7 commented Aug 26, 2026

Copy link
Copy Markdown
Member

Summary

copyEvalMirror() in scripts/release-cli-package.mjs copied the entire staged node_modules/@maka/eval tree into packages/eval inside the published CLI package, so every install carried the Eval runtime twice and the two copies could diverge between releases.

The mirror is not pure redundancy. Eval containers bind-mount the CLI package root read-only at /opt/maka-agent (packages/cli/src/eval-bundle-path.ts sets MAKA_EVAL_MAKA_BUNDLE_PATH to the package root; the experiment mount resolves in packages/eval/src/harness-executor.ts), so /opt/maka-agent/packages/eval/... resolves to the mirror. Only a small container-facing subset is actually read from it; the host Eval runtime is read once from node_modules/@maka/eval.

stageEvalMirror() now ships only that subset (16 files, down from the whole runtime tree):

  • Container entry points (launched inside eval cells): dist/harbor-external-subject.js, dist/harbor-maka-subject.js.
  • Their transitive import closure (8 more dist/*.js).
  • Harbor data / egress assets the entry points resolve: harbor/deepseek-codex-models.json, the harbor/deepseek-harness-profile directory, harbor/docker-compose-egress-proxy.yaml, harbor/egress-proxy/network-policy.

Dropped from the mirror (all remain in node_modules/@maka/eval via releaseFiles): the host-only dist/*.js modules; the harbor Python launchers (read from node_modules/@maka/eval/harbor via BUNDLED_HARNESS_RELAY_ROOT, not through the mount); and the egress image-build inputs (CI-only). The relay_agent.py/run_trial.py release guards move from the mirror to node_modules/@maka/eval, matching where the runtime resolves them.

maka eval remains the only public Eval CLI. Behavior, standalone packaging, and every container path the experiments depend on are unchanged.

Fixes #3933

The reduction is proven structurally, not by text heuristics

  • Real parser for the closure. The import graph is walked with acorn, so imports split across comments are followed and a string that merely contains import( is not mistaken for a dependency. A dynamic import() with a computed specifier is refused (fail closed) because its closure cannot be resolved.
  • Structured config checking. Experiment configs are JSON.parsed and every string value is checked; each packages/eval reference is normalized (resolving ./..) and rejected if it escapes the mirror, so neither path traversal (.../deepseek-harness-profile/../secret.json) nor a JSON-escaped slash (packages\/eval\/...) can name an unshipped file undetected.
  • Single directory authority. deepseek-harness-profile is declared once, as a directory, in the eval package's releaseFiles; staging and the mirror both copy it whole, so a newly required profile file cannot reach the runtime yet be missed by the mirror.
  • Production-wiring assertion. validatePackedFiles recomputes the mirror inventory from the staged runtime independently of copyEvalMirror and asserts the packed packages/eval files match it exactly — so reverting to a whole-tree copy, or dropping a required file, fails the release. The installed smoke test additionally asserts no host-only file appears under the mirror.

Verification

  • node --test scripts/release-cli-file-policy.test.mjs — 24/24 pass, incl. comment-split imports, computed-import() rejection, path-traversal and JSON-escape rejection, the exact fixture inventory (a whole-tree copy fails it), and assertPackedEvalMirror rejecting a reintroduced host-only file. Affected suites together: 32/32.
  • Real development release build (node scripts/release-cli-package.mjs --development) succeeded end to end: the profile directory is copied whole into node_modules/@maka/eval, the mirror stages to exactly 16 files, and validatePackedFiles (with the new packed-mirror assertion) passed. Tarball: 13.7 MiB compressed, 6408 files.
  • biome check (lint + format) clean on all changed files.
  • Not run locally (needs Docker; runs in CI): release-cli-eval-package.mjs, which installs the tarball and runs real Harbor + Pier Docker cells. Please confirm the release:cli:eval job on CI.

Dependency

Adds acorn (already present transitively) as a direct devDependency so the release script can depend on it for parsing.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code (Opus) — mapped the runtime consumption of the mirror, implemented stageEvalMirror and its tests, and drafted this description. A human contributor reviewed and owns the change. The commit carries a Generated-by: Claude Opus trailer.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl branch 2 times, most recently from 2927cd0 to 1f5e94d Compare August 26, 2026 18:46
@github-actions github-actions Bot added the effort/L Under 1000 readable lines label Aug 27, 2026
@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl branch 5 times, most recently from 7b230a8 to 76d4f20 Compare August 29, 2026 09:33

@Astro-Han Astro-Han left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for tracing the Eval packaging consumers and reducing the duplicated payload.

I reviewed the exact head. The current 16-file inventory matches the existing container entry points, their import closure, and the Harbor/egress assets they consume. I did not find a P0 or P1 correctness issue in the current artifact.

I left one P2 inline about the architectural end state. The change reduces packaged bytes, but it retains the mirror and introduces substantial machinery to keep that second representation synchronized. I think the simplification should aim for one physical Eval runtime and strictly fewer maintained concepts, unless the old container path has a demonstrated external compatibility obligation.

AI-assisted review disclosure: Codex assisted with tracing the exact-head packaging, mount, experiment-config, and release-validation paths. I reviewed the recommendation and own this review.

Comment thread scripts/release-cli-package.mjs Outdated
@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl branch from 76d4f20 to a4c58c8 Compare August 30, 2026 13:30
copyEvalMirror() copied the whole staged node_modules/@maka/eval tree into
packages/eval, so every install carried the Eval runtime twice and the two
copies could diverge between releases.

Ship the runtime once. The CLI package root is bind-mounted read-only at
/opt/maka-agent inside eval containers (eval-bundle-path.ts sets
MAKA_EVAL_MAKA_BUNDLE_PATH to the package root; the experiment mount resolves in
harness-executor.ts), and the canonical runtime already ships at
node_modules/@maka/eval via the eval package's releaseFiles (the whole dist plus
the harbor assets). So the container-facing paths are repointed from
/opt/maka-agent/packages/eval/... to /opt/maka-agent/node_modules/@maka/eval/...:
the two container entry points (harbor-external-subject.js / harbor-maka-subject.js,
named by an experiment's args[0] / shimPath), the codex model catalog and the
deepseek-harness profile the external subject reads, and the egress
compose/network-policy resolved from the bundle. eval-bundle-path.ts keys its
installed-CLI guard on node_modules/@maka/eval.

With every consumer pointed at the canonical runtime, the mirror and the
machinery that proved it are deleted outright: copyEvalMirror/stageEvalMirror, the
acorn-based import-closure and path analyzer, the mirror inventory and the
packed-tarball reconciliation, the acorn devDependency, and the mirror
synchronization tests. The release packs node_modules/@maka/eval and no longer
stages a packages/eval copy; validateStaging and the installed smoke test assert
the container entry point, relay_agent.py, the egress compose, and the
network-policy ship under node_modules/@maka/eval. maka eval remains the only
public Eval CLI.

Generated-by: Claude Opus
@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-cli-ship-one-eval-runtime-in-the-npm-cl branch from a4c58c8 to 78e56a7 Compare August 30, 2026 14:27
@liuxiaocs7
liuxiaocs7 requested a review from Astro-Han August 30, 2026 14:31

@Astro-Han Astro-Han left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for taking this through to the single-runtime end state.

I independently rechecked exact head 78e56a7882110657fb61b75c5eae286a49d9d26d against the current main. The Eval mirror and its synchronization machinery are gone, the internal consumers now use the packaged @maka/eval runtime, the prior thread is resolved, and the exact-head required checks are green. I found no remaining P0-P3 issue.

Please do push back if there is a deployment or compatibility consumer that is not visible from the checked-in production paths; the conclusion here is based on the repository and hosted evidence available at this head.

中文对照

感谢将改动收敛到单一 Eval runtime。已独立复核当前 exact head 与 current main;旧镜像及同步机制已删除,内部消费者统一使用打包的 @maka/eval,旧线程已解决,当前提交的必要检查均通过,未发现剩余 P0-P3。若存在仓库生产路径之外的部署或兼容消费者,也欢迎补充或反驳。

AI-assisted review disclosure: Codex ran independent analysis lanes; Astro-Han independently verified the exact head, current-main integration, production ownership, and merge gates, and owns this review.

@Astro-Han
Astro-Han merged commit 9793520 into apache:main Aug 30, 2026
13 checks passed
saltand pushed a commit to saltand/maka-agent that referenced this pull request Aug 31, 2026
)

copyEvalMirror() copied the whole staged node_modules/@maka/eval tree into
packages/eval, so every install carried the Eval runtime twice and the two
copies could diverge between releases.

Ship the runtime once. The CLI package root is bind-mounted read-only at
/opt/maka-agent inside eval containers (eval-bundle-path.ts sets
MAKA_EVAL_MAKA_BUNDLE_PATH to the package root; the experiment mount resolves in
harness-executor.ts), and the canonical runtime already ships at
node_modules/@maka/eval via the eval package's releaseFiles (the whole dist plus
the harbor assets). So the container-facing paths are repointed from
/opt/maka-agent/packages/eval/... to /opt/maka-agent/node_modules/@maka/eval/...:
the two container entry points (harbor-external-subject.js / harbor-maka-subject.js,
named by an experiment's args[0] / shimPath), the codex model catalog and the
deepseek-harness profile the external subject reads, and the egress
compose/network-policy resolved from the bundle. eval-bundle-path.ts keys its
installed-CLI guard on node_modules/@maka/eval.

With every consumer pointed at the canonical runtime, the mirror and the
machinery that proved it are deleted outright: copyEvalMirror/stageEvalMirror, the
acorn-based import-closure and path analyzer, the mirror inventory and the
packed-tarball reconciliation, the acorn devDependency, and the mirror
synchronization tests. The release packs node_modules/@maka/eval and no longer
stages a packages/eval copy; validateStaging and the installed smoke test assert
the container entry point, relay_agent.py, the egress compose, and the
network-policy ship under node_modules/@maka/eval. maka eval remains the only
public Eval CLI.

Generated-by: Claude Opus
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/L Under 1000 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(cli): ship one Eval runtime in the npm CLI package

2 participants