Skip to content

Commit b83ffe2

Browse files
authored
fix: repair NemoHermes first-run onboarding (#2781)
## Summary - make NemoHermes default to a Hermes sandbox name and keep installer next-step output tied to the actual onboard session - prevent silent same-name cross-agent reuse while preserving side-by-side OpenClaw and Hermes sandboxes under the shared OpenShell gateway - persist per-sandbox agent metadata/default selection on create and reuse, make Hermes setup failures fatal, and add clearer typo/command-order diagnostics - show per-sandbox agent type in list output Supersedes #2780, which was closed because the repository blocks force-pushing the amended DCO-signed commit. ## Validation - npm run build:cli - npx vitest run test/install-preflight.test.ts test/cli.test.ts test/onboard.test.ts src/lib/agent-onboard.test.ts src/lib/inventory-commands.test.ts --maxWorkers=1 - npx vitest run test/nemohermes-alias.test.ts - npx vitest run src/lib/inventory-commands.test.ts src/lib/agent-onboard.test.ts - git diff --check <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Inventory shows per-sandbox agent; CLI gives typo suggestions and command-order hints; agent-aware sandbox naming and UI labels; installer prefers and exposes user-local OpenShell; dashboard forwarding reduces port collisions and restores agent forwards (Hermes-specific restore/watch added). * **Bug Fixes** * Agent preflight verifies binaries and in-sandbox probes; fails fast on unreachable gateways; blocks sandbox reuse on agent/image drift. * **Tests** * Expanded coverage across onboarding, installer helpers, OpenShell resolution, Docker validation, CLI suggestions, and provisioning. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 8770440 commit b83ffe2

14 files changed

Lines changed: 1222 additions & 77 deletions

‎agents/hermes/Dockerfile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,17 @@ ARG BASE_IMAGE=ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest
1111
# hadolint ignore=DL3006
1212
FROM ${BASE_IMAGE}
1313

14+
# Keep the final image contract explicit even when the published base image
15+
# changes independently of this Dockerfile.
16+
RUN set -eu; \
17+
hermes_path="$(command -v hermes 2>/dev/null || true)"; \
18+
if [ "$hermes_path" != "/usr/local/bin/hermes" ]; then \
19+
echo "ERROR: expected hermes at /usr/local/bin/hermes, got ${hermes_path:-missing}" >&2; \
20+
exit 1; \
21+
fi; \
22+
test -x /usr/local/bin/hermes; \
23+
/usr/local/bin/hermes --version
24+
1425
# Harden: remove unnecessary build tools and network probes
1526
RUN (apt-get remove --purge -y gcc gcc-12 g++ g++-12 cpp cpp-12 make \
1627
netcat-openbsd netcat-traditional ncat 2>/dev/null || true) \

‎scripts/install.sh‎

Lines changed: 162 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,19 @@ installer_version_for_display() {
8989
printf " v%s" "$NEMOCLAW_VERSION"
9090
}
9191

92+
agent_display_name() {
93+
case "${1:-}" in
94+
hermes) printf "Hermes" ;;
95+
openclaw | "") printf "OpenClaw" ;;
96+
*)
97+
local first rest
98+
first="$(printf "%.1s" "$1" | tr '[:lower:]' '[:upper:]')"
99+
rest="${1#?}"
100+
printf "%s%s" "$first" "$rest"
101+
;;
102+
esac
103+
}
104+
92105
# Resolve which Git ref to install from.
93106
# Priority: NEMOCLAW_INSTALL_TAG env var > "latest" tag.
94107
resolve_release_tag() {
@@ -172,13 +185,13 @@ verify_downloaded_script() {
172185

173186
resolve_default_sandbox_name() {
174187
local registry_file="${HOME}/.nemoclaw/sandboxes.json"
175-
local sandbox_name="${NEMOCLAW_SANDBOX_NAME:-}"
188+
local sandbox_name=""
176189

177190
# Prefer the sandbox name from the current onboard session — it reflects
178191
# the sandbox just created, whereas sandboxes.json may hold a stale default
179192
# from a previous gateway that no longer exists (#1839).
180193
local session_file="${HOME}/.nemoclaw/onboard-session.json"
181-
if [[ -z "$sandbox_name" && -f "$session_file" ]] && command_exists node; then
194+
if [[ -f "$session_file" ]] && command_exists node; then
182195
sandbox_name="$(
183196
node -e '
184197
const fs = require("fs");
@@ -190,6 +203,16 @@ resolve_default_sandbox_name() {
190203
' "$session_file" 2>/dev/null || true
191204
)"
192205
fi
206+
if [[ -z "$sandbox_name" && -f "$session_file" ]]; then
207+
sandbox_name="$(
208+
sed -n 's/.*"sandboxName"[[:space:]]*:[[:space:]]*"\([^"\\]*\)".*/\1/p' "$session_file" 2>/dev/null \
209+
| head -n 1
210+
)"
211+
fi
212+
213+
if [[ -z "$sandbox_name" ]]; then
214+
sandbox_name="${NEMOCLAW_SANDBOX_NAME:-}"
215+
fi
193216

194217
if [[ -z "$sandbox_name" && -f "$registry_file" ]] && command_exists node; then
195218
sandbox_name="$(
@@ -207,7 +230,11 @@ resolve_default_sandbox_name() {
207230
)"
208231
fi
209232

210-
printf "%s" "${sandbox_name:-my-assistant}"
233+
local fallback="my-assistant"
234+
if [[ "${NEMOCLAW_AGENT:-}" == "hermes" ]]; then
235+
fallback="hermes"
236+
fi
237+
printf "%s" "${sandbox_name:-$fallback}"
211238
}
212239

213240
resolve_onboarded_agent() {
@@ -225,6 +252,125 @@ resolve_onboarded_agent() {
225252
fi
226253
}
227254

255+
restore_onboard_forward_after_post_checks() {
256+
local sandbox_name agent_name agent_display port openshell_bin attempt state_dir pid_file watcher_script watcher_pid
257+
sandbox_name="$(resolve_default_sandbox_name)"
258+
agent_name="$(resolve_onboarded_agent)"
259+
agent_display="$(agent_display_name "$agent_name")"
260+
261+
case "$agent_name" in
262+
hermes) port=8642 ;;
263+
*) return 0 ;;
264+
esac
265+
266+
if [[ -n "${NEMOCLAW_OPENSHELL_BIN:-}" && -x "$NEMOCLAW_OPENSHELL_BIN" ]]; then
267+
openshell_bin="$NEMOCLAW_OPENSHELL_BIN"
268+
elif command_exists openshell; then
269+
openshell_bin="$(command -v openshell)"
270+
else
271+
return 0
272+
fi
273+
274+
state_dir="${HOME}/.nemoclaw/state"
275+
mkdir -p "$state_dir" 2>/dev/null || true
276+
pid_file="${state_dir}/${agent_name}-${sandbox_name}-${port}.forward.pid"
277+
if [[ -f "$pid_file" ]]; then
278+
local old_pid expected_watcher_script current_uid old_uid old_args
279+
old_pid="$(cat "$pid_file" 2>/dev/null || true)"
280+
expected_watcher_script="${pid_file}.js"
281+
current_uid="$(id -u)"
282+
if [[ "$old_pid" =~ ^[0-9]+$ ]] && kill -0 "$old_pid" >/dev/null 2>&1; then
283+
old_uid="$(ps -p "$old_pid" -o uid= 2>/dev/null | tr -d '[:space:]' || true)"
284+
old_args="$(ps -p "$old_pid" -o args= 2>/dev/null || true)"
285+
if [[ "$old_uid" == "$current_uid" && "$old_args" == *"$expected_watcher_script"* ]]; then
286+
kill "$old_pid" >/dev/null 2>&1 || true
287+
fi
288+
fi
289+
rm -f "$pid_file"
290+
fi
291+
292+
stop_agent_forward_if_owned() {
293+
local forward_list owner status
294+
"$openshell_bin" forward stop "$port" "$sandbox_name" >/dev/null 2>&1 && return 0
295+
forward_list="$("$openshell_bin" forward list 2>/dev/null || true)"
296+
owner="$(awk -v sandbox="$sandbox_name" -v port="$port" '
297+
$1 == sandbox && $3 == port {
298+
print $1
299+
exit
300+
}
301+
' <<<"$forward_list")"
302+
status="$(awk -v sandbox="$sandbox_name" -v port="$port" '
303+
$1 == sandbox && $3 == port {
304+
print tolower($5)
305+
exit
306+
}
307+
' <<<"$forward_list")"
308+
if [[ "$owner" == "$sandbox_name" && ("$status" == "running" || "$status" == "active") ]]; then
309+
"$openshell_bin" forward stop "$port" "$sandbox_name" >/dev/null 2>&1 || true
310+
fi
311+
}
312+
313+
for attempt in 1 2 3; do
314+
stop_agent_forward_if_owned
315+
if [ "$attempt" -gt 1 ]; then
316+
sleep 2
317+
fi
318+
"$openshell_bin" forward start --background "$port" "$sandbox_name" >/dev/null 2>&1 || true
319+
watcher_pid=""
320+
if [[ "${NEMOCLAW_SKIP_FORWARD_WATCHER:-}" != "1" ]] && command_exists node; then
321+
watcher_script="${pid_file}.js"
322+
cat >"$watcher_script" <<'NODE'
323+
const { spawnSync } = require("child_process");
324+
const [openshellBin, port, sandboxName] = process.argv.slice(2);
325+
function run(args) {
326+
spawnSync(openshellBin, args, { stdio: "ignore" });
327+
}
328+
function healthy() {
329+
return spawnSync("curl", ["-sf", "--max-time", "3", `http://127.0.0.1:${port}/health`], {
330+
stdio: "ignore",
331+
}).status === 0;
332+
}
333+
function tick() {
334+
if (healthy()) return;
335+
run(["forward", "stop", port, sandboxName]);
336+
run(["forward", "start", "--background", port, sandboxName]);
337+
}
338+
tick();
339+
setInterval(tick, 10_000);
340+
NODE
341+
node -e '
342+
const { spawn } = require("child_process");
343+
const fs = require("fs");
344+
const [script, openshellBin, port, sandboxName, pidFile] = process.argv.slice(1);
345+
const child = spawn(process.execPath, [script, openshellBin, port, sandboxName], {
346+
detached: true,
347+
stdio: "ignore",
348+
});
349+
fs.writeFileSync(pidFile, String(child.pid) + "\n");
350+
child.unref();
351+
' "$watcher_script" "$openshell_bin" "$port" "$sandbox_name" "$pid_file" \
352+
>/dev/null 2>&1 || true
353+
fi
354+
sleep 4
355+
if command_exists curl \
356+
&& curl -sf --max-time 3 "http://127.0.0.1:${port}/health" >/dev/null 2>&1; then
357+
return 0
358+
fi
359+
watcher_pid="$(cat "$pid_file" 2>/dev/null || true)"
360+
if ! command_exists curl && [[ -n "$watcher_pid" ]] && kill -0 "$watcher_pid" >/dev/null 2>&1; then
361+
return 0
362+
fi
363+
if [[ -n "$watcher_pid" ]]; then
364+
kill "$watcher_pid" >/dev/null 2>&1 || true
365+
fi
366+
rm -f "$pid_file"
367+
done
368+
369+
warn "Could not restore ${agent_display} host forward on port ${port}."
370+
warn "Run: openshell forward start --background ${port} ${sandbox_name}"
371+
return 1
372+
}
373+
228374
# step N "Description" — numbered section header
229375
step() {
230376
local n=$1 msg=$2
@@ -255,7 +401,7 @@ print_banner() {
255401
fi
256402
printf "\n"
257403
if [[ -n "${NEMOCLAW_AGENT:-}" && "${NEMOCLAW_AGENT}" != "openclaw" ]]; then
258-
printf " ${C_DIM}Launch %s in an OpenShell sandbox.%s${C_RESET}\n" "${NEMOCLAW_AGENT^}" "$version_suffix"
404+
printf " ${C_DIM}Launch %s in an OpenShell sandbox.%s${C_RESET}\n" "$(agent_display_name "$NEMOCLAW_AGENT")" "$version_suffix"
259405
else
260406
printf " ${C_DIM}Launch OpenClaw in an OpenShell sandbox.%s${C_RESET}\n" "$version_suffix"
261407
fi
@@ -278,7 +424,7 @@ print_done() {
278424
if [[ "$agent_name" == "openclaw" || -z "$agent_name" ]]; then
279425
printf " ${C_GREEN}Your OpenClaw Sandbox is live.${C_RESET}\n"
280426
else
281-
printf " ${C_GREEN}Your %s Sandbox is live.${C_RESET}\n" "${agent_name^}"
427+
printf " ${C_GREEN}Your %s Sandbox is live.${C_RESET}\n" "$(agent_display_name "$agent_name")"
282428
fi
283429
printf " ${C_DIM}Sandbox in, break things, and tell us what you find.${C_RESET}\n"
284430
printf "\n"
@@ -593,6 +739,15 @@ refresh_path() {
593739
fi
594740
}
595741

742+
prefer_user_local_openshell() {
743+
local local_bin="${XDG_BIN_HOME:-${HOME}/.local/bin}"
744+
local openshell_bin="${local_bin}/openshell"
745+
if [[ -x "$openshell_bin" ]]; then
746+
export NEMOCLAW_OPENSHELL_BIN="$openshell_bin"
747+
export PATH="$local_bin:$PATH"
748+
fi
749+
}
750+
596751
ensure_cli_shim() {
597752
local cli_bin="${1:-$_CLI_BIN}"
598753
local npm_bin shim_path node_path node_dir cli_path
@@ -1181,6 +1336,7 @@ install_nemoclaw() {
11811336
# running ./scripts/install.sh manages their own openshell. The script is
11821337
# idempotent on the happy path. See #2272.
11831338
spin "Installing OpenShell CLI" bash "${NEMOCLAW_SOURCE_ROOT}/scripts/install-openshell.sh"
1339+
prefer_user_local_openshell
11841340
fi
11851341

11861342
refresh_path
@@ -1579,6 +1735,7 @@ except Exception:
15791735
info "Checking for sandboxes that need upgrading…"
15801736
"$_CLI_BIN" upgrade-sandboxes --auto 2>&1 || warn "Sandbox upgrade check failed (non-fatal)."
15811737
fi
1738+
restore_onboard_forward_after_post_checks || error "Hermes host forward restore failed."
15821739
else
15831740
warn "Skipping onboarding until the host prerequisites above are fixed."
15841741
fi

‎src/lib/agent-onboard.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
// SPDX-License-Identifier: Apache-2.0
33

44
import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from "vitest";
5+
import fs from "node:fs";
6+
import path from "node:path";
57
// Import from compiled dist/ so coverage is attributed correctly.
68
import { printDashboardUi } from "../../dist/lib/agent-onboard";
79
import type { AgentDefinition } from "./agent-defs";
@@ -120,3 +122,32 @@ describe("printDashboardUi — regression for #2078 (port 8642 is not a chat UI)
120122
expect(output).toContain("http://127.0.0.1:19000/#token=tok");
121123
});
122124
});
125+
126+
describe("handleAgentSetup guards", () => {
127+
it("fails onboarding instead of completing when the agent binary or health probe is missing", () => {
128+
const source = fs.readFileSync(path.join(import.meta.dirname, "agent-onboard.ts"), "utf-8");
129+
130+
expect(source).toContain("verifyAgentBinaryAvailable");
131+
expect(source).toContain(
132+
'resolved="$(command -v ${shellQuote(executable)} 2>/dev/null || true)"',
133+
);
134+
expect(source).toContain('[ "$resolved" = ${shellQuote(binaryPath)} ]');
135+
expect(source).toMatch(
136+
/"sandbox",\s*"exec",\s*"-n",\s*sandboxName,\s*"--",\s*"sh",\s*"-lc",\s*script/,
137+
);
138+
expect(source).not.toMatch(/\["sandbox",\s*"exec",\s*sandboxName,\s*"sh"/);
139+
expect(source).toContain("failAgentSetup");
140+
expect(source).toContain('onboardSession.markStepFailed("agent_setup"');
141+
expect(source).toContain("gateway did not respond within");
142+
expect(source).not.toContain("gateway may still be starting");
143+
});
144+
145+
it("accepts Hermes JSON health responses without substring false positives", () => {
146+
const source = fs.readFileSync(path.join(import.meta.dirname, "agent-onboard.ts"), "utf-8");
147+
148+
expect(source).toContain("function isHealthProbeOk");
149+
expect(source).toContain("JSON.parse(body)");
150+
expect(source).toContain('parsed.status === "ok"');
151+
expect(source).not.toContain('.includes("ok")');
152+
});
153+
});

0 commit comments

Comments
 (0)