feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper by easel · Pull Request #335 · Luce-Org/lucebox-hub

easel · 2026-06-03T21:29:59Z

Summary

Adds the lucebox hub CLI (autotune, sweep, profile, smoke, models, config, download, host-check, docker_run) plus the lucebox.sh wrapper and install.sh bootstrap. Also lands the harness/ adapter package (claude_code, codex, hermes, openclaw, opencode, pi) and the run_lucebench.sh shim that lucebox bench-style flows shell out to. Additive only — no existing source files modified outside CI workflow edits, README touch-ups, and a lefthook.yml for the new packages.

Files

lucebox/ — new Python package: CLI entrypoint, autotune/sweep/profile/smoke/config/download/host-check/docker_run modules, full pytest suite under lucebox/tests/.
harness/ — new Python package: harness.bench + per-agent client adapters (claude_code.py, codex.py, hermes.py, openclaw.py, opencode.py, pi.py) and the run_lucebench.sh operator shim.
lucebox.sh + install.sh — top-level shell wrapper and bootstrap installer.
scripts/check_lucebox_wrapper_sandbox.sh, scripts/test_lucebox_sh.sh — wrapper-shape integration tests.
.github/workflows/ci.yml — wires the new packages into CI.
harness/clients/README.md, lefthook.yml — supporting docs/config.

Single commit, ~10.5k LOC added across 49 files.

Dependencies

build(docker): lucebox-hub container image + CI release pipeline #334 (docker-stack) — lucebox.docker_run shells out to docker run against the lucebox-hub image and reads the IMAGE_INFO produced by the docker build. The CLI cannot exercise a real run path until docker-stack lands.
feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337 (luce-bench) — harness/bench.py invokes python -m lucebench.cli ... as a subprocess; harness/clients/run_lucebench.sh is the operator shim around the same package. Both require the lucebench package to be importable.
refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 (server-layer-split) — autotune candidate configs assume the layer-split build flags surfaced by the server build artifacts; without refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 the configs reduce to no-ops on real hardware.

Unit tests in lucebox/tests/ and harness/ mock the external surfaces and pass standalone, but end-to-end validation requires the three siblings above.

Test plan

cd lucebox && uv run pytest (standalone — mocks docker/lucebench surfaces)
cd harness && uv run pytest (standalone)
./lucebox.sh --help resolves once build(docker): lucebox-hub container image + CI release pipeline #334 lands and the image is available
lucebox host-check reports GPU + driver facts on a fresh host
lucebox autotune --dry-run enumerates candidate configs without launching a sweep
End-to-end lucebox bench-style flow once feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337 (luce-bench) is mergeable and refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336 (server layer-split) is exposing the expected build flags

Note: this PR's CLI/adapter code is self-contained and unit-tests pass standalone, but full integration validation requires the docker, luce-bench, and server-layer-split siblings to land together.

Generated with Claude Code

## What Containerization stack for lucebox-hub. Dockerfile + docker-bake.hcl build the lucebox-hub image (build-env and runtime stages); scripts/build_image.sh drives local builds; server/scripts/entrypoint.sh emits IMAGE_INFO / HOST_INFO sidecars consumed by /props. GitHub Actions add .github/workflows/docker.yml (build & publish), update ci.yml, and add release-luce-bench.yml for tagging. Workspace-root files (pyproject.toml, uv.lock, Makefile, lefthook.yml, .gitignore, README) live here because the Dockerfile uv-syncs the workspace at build time. ## Why Provides the reproducible image and CI pipeline every other split PR deploys into. Centralizing build/publish here keeps Dockerfile, entrypoint, and workspace-root pinning in one reviewable change. ## Dependencies - Luce-Org#335 (lucebox-cli): Dockerfile COPYs lucebox/ into the image - Luce-Org#337 (lucebench-harness): Dockerfile COPYs luce-bench/ into the image

cubic-dev-ai

29 issues found across 52 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lucebox/src/lucebox/docker_run.py">

<violation number="1" location="lucebox/src/lucebox/docker_run.py:231">
P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai · 2026-06-04T19:33:00Z

+# ── subprocess helpers ─────────────────────────────────────────────────────
+
+
+def run(argv: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:


P3: Several newly added helper functions are dead code (defined but never called anywhere in the codebase).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lucebox/src/lucebox/docker_run.py, line 231: <comment>Several newly added helper functions are dead code (defined but never called anywhere in the codebase).</comment> <file context> @@ -0,0 +1,270 @@ +# ── subprocess helpers ───────────────────────────────────────────────────── + + +def run(argv: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]: + """Run a command, streaming stdout/stderr to the user. `check=False` to + inspect exit codes manually.""" </file context>

Fixed in 73f04f4: removed the unused run(), docker_inspect_running(), host_path_visible(), and stderr() helpers from docker_run.py, plus the now-unused sys import.

Thanks for the update!

Containerization stack for lucebox-hub. Dockerfile + docker-bake.hcl build the lucebox-hub image (build-env and runtime stages); scripts/build_image.sh drives local builds; server/scripts/entrypoint.sh emits IMAGE_INFO / HOST_INFO sidecars consumed by /props. GitHub Actions add .github/workflows/docker.yml (build & publish), update ci.yml, and add release-luce-bench.yml for tagging. Workspace-root files (pyproject.toml, uv.lock, Makefile, lefthook.yml, .gitignore, README) live here because the Dockerfile uv-syncs the workspace at build time. Provides the reproducible image and CI pipeline every other split PR deploys into. Centralizing build/publish here keeps Dockerfile, entrypoint, and workspace-root pinning in one reviewable change. - Luce-Org#335 (lucebox-cli): Dockerfile COPYs lucebox/ into the image - Luce-Org#337 (lucebench-harness): Dockerfile COPYs luce-bench/ into the image

…R + personal refs Strip forward-references to lucebox-cli (Luce-Org#335) and luce-bench (Luce-Org#337) plus the contributor's personal repos so the docker stack stands alone: - delete .github/workflows/release-luce-bench.yml (luce-bench PyPI publish; fires only on luce-bench-v* tags, needs a luce-bench/ dir not in this repo) - Makefile: drop test/smoke/bench/profile targets (invoke lucebench/lucebox modules absent here) and their now-unused vars - .gitignore: drop luce-bench/snapshots and external baseline-repo URLs - pyproject.toml / Dockerfile / docker.yml: de-reference Luce-Org#335/Luce-Org#337/luce-bench in comments No functional change: deps, workspace members, ruff config, and every build instruction are untouched, so CI stays green. The siblings re-add their own scaffolding when they land. Co-Authored-By: WOZCODE <contact@withwoz.com>

… adapters New lucebox/ Python package exposing the hub CLI (autotune, sweep, profile, smoke, models, config, download, host-check, docker_run) plus the lucebox.sh launcher wrapper and install.sh. Adds the harness/ adapter package wrapping external coding agents (claude_code, codex, hermes, openclaw, opencode, pi) that autotune sweeps drive. Ships scripts/check_lucebox_wrapper_sandbox.sh and scripts/test_lucebox_sh.sh for wrapper validation, full pytest coverage under lucebox/tests/, and the bragi autotune profile-sweep protocol docs. This is the user-facing surface of lucebox-hub: one CLI to launch the image, tune layer-split / pflash settings against a host, run sweeps, and dispatch bench runs. Splitting it out keeps Python-side review independent of the C++ server and Docker stack reviews. - Luce-Org#334 (docker-stack): docker_run.py launches the lucebox-hub image - Luce-Org#337 (lucebench-harness): lucebox bench delegates to luce-bench (workspace dep) - Luce-Org#336 (server-layer-split): autotune presumes layer-split build artifacts

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…to-auto-pick entrypoint.sh:write_host_info() bailed loudly when /opt/lucebox-hub/ did not exist on the host (unit tests, plain docker run without bind mount), because bash refuses the > redirect before the command runs and 2>/dev/null does not suppress the redirect's own error. Guard with an upfront [ -d ] check. test_lucebox_sh.sh:test_entrypoint_multi_target was asserting against the pre-Luce-Org#334 multi-target semantics (auto-pick + warn + exec shim). PR Luce-Org#334 (merged) changed that to refuse-to-auto-pick + exit non-zero. Update the assertion: still drives the auto-detect block (so any DRAFT_FAMILY_GLOB set -u regression trips), but now requires the refuse warn to fire and the shim to NOT exec. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

cubic-dev-ai

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/test_lucebox_sh.sh">

<violation number="1" location="scripts/test_lucebox_sh.sh:511">
P2: The regression test no longer asserts that multi-target auto-detect exits non-zero, so a refusal path that logs the warning but returns success would slip through.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai · 2026-06-11T15:29:25Z

+    # was NOT exec'd (a silent multi-target auto-pick would be the bug).
+    if grep -qE 'unbound variable|syntax error' <<<"$out"; then
+        report fail "$label" "leak: $(grep -E 'unbound variable|syntax error' <<<"$out" | head -3)"
+    elif ! grep -qF "Refusing to auto-select" <<<"$out"; then


P2: The regression test no longer asserts that multi-target auto-detect exits non-zero, so a refusal path that logs the warning but returns success would slip through.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/test_lucebox_sh.sh, line 511: <comment>The regression test no longer asserts that multi-target auto-detect exits non-zero, so a refusal path that logs the warning but returns success would slip through.</comment> <file context> @@ -501,14 +501,17 @@ STUB - report fail "$label" "shim never executed; output: $(head -10 <<<"$out")" - elif ! grep -qF "Multiple candidate targets" <<<"$out"; then - report fail "$label" "multi-target warn missing — did the auto-detect block fire?" + elif ! grep -qF "Refusing to auto-select" <<<"$out"; then + report fail "$label" "refuse-to-auto-pick warn missing — did the auto-detect block fire? rc=$rc output: $(head -5 <<<"$out")" + elif grep -qF "[shim] dflash_server" <<<"$out"; then </file context>

Suggested change

elif ! grep -qF "Refusing to auto-select" <<<"$out"; then

elif [ "$rc" = "0" ]; then

report fail "$label" "expected non-zero exit on ambiguous target; output: $(head -5 <<<"$out")"

elif ! grep -qF "Refusing to auto-select" <<<"$out"; then

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 91276a7 to 62b21f0 Compare June 4, 2026 02:50

This was referenced Jun 4, 2026

feat(luce-bench): in-tree bench harness + multi-turn agent_recorded + LLM judge #337

Open

build(docker): lucebox-hub container image + CI release pipeline #334

Merged

refactor(server): shared layer-split backend + GGUF inspection + c2-gate plumbing #336

Closed

easel force-pushed the feat/lucebox-cli branch from 62b21f0 to 8732b35 Compare June 4, 2026 05:02

easel mentioned this pull request Jun 4, 2026

feat(lucebox): docker stack + CLI + bench/profile + harness + luce-bench in-tree #285

Closed

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 6c9078b to 360d332 Compare June 4, 2026 17:17

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from 1d588db to 0d8e1ff Compare June 4, 2026 18:38

easel marked this pull request as ready for review June 4, 2026 19:18

cubic-dev-ai Bot reviewed Jun 4, 2026

View reviewed changes

easel force-pushed the feat/lucebox-cli branch from 0d8e1ff to 73f04f4 Compare June 4, 2026 23:30

easel pushed a commit to easel/lucebox-hub that referenced this pull request Jun 5, 2026

docs: refresh auto-integration manifest for PR Luce-Org#335 probe

0c8511f

easel force-pushed the feat/lucebox-cli branch 2 times, most recently from bb7bb11 to a56b51b Compare June 8, 2026 22:08

easel force-pushed the feat/lucebox-cli branch from a56b51b to fb084b5 Compare June 11, 2026 01:55

easel and others added 2 commits June 11, 2026 11:15

fix(harness): drop unused subprocess import in codex client (ruff F401)

c46e358

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

easel force-pushed the feat/lucebox-cli branch from 5a7e617 to c46e358 Compare June 11, 2026 15:15

cubic-dev-ai Bot reviewed Jun 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper#335

feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper#335
easel wants to merge 3 commits into
Luce-Org:mainfrom
easel:feat/lucebox-cli

easel commented Jun 3, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot Jun 4, 2026

Uh oh!

easel Jun 4, 2026

Uh oh!

cubic-dev-ai Bot Jun 4, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		# ── subprocess helpers ─────────────────────────────────────────────────────


		def run(argv: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:

Conversation

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

Uh oh!

Summary

Files

Dependencies

Test plan

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

easel Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

easel commented Jun 3, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading