jishushell 0.4.17 → 0.4.24-beta.2

package/scripts/check-adapter-isolation.ts

@@ -0,0 +1,293 @@
+#!/usr/bin/env -S node --experimental-strip-types
+/**
+ * check-adapter-isolation — §32.2.1 static enforcement + §30.3 fixtures.
+ *
+ * Two invariants:
+ *
+ *   1. Core framework files never import from
+ *      `src/services/runtime/adapters/*`. Adapters load exclusively through
+ *      `src/services/runtime/index.ts` side-effect imports, and framework
+ *      code reaches adapters through `getAdapter(kind)` only.
+ *
+ *   2. Fixture `instance.json` samples under
+ *      `scripts/fixtures/instances/<name>/` satisfy the minimum meta
+ *      contract: `id`, `name`, resolvable agent discriminator, and
+ *      (for Hermes) the required `paths.agentHome` / `paths.primaryConfig`
+ *      / `paths.secretEnv` entries. Legacy openclaw samples round-trip
+ *      through `backfillInstanceMeta` to `agentType="openclaw"`.
+ *
+ * Run via `npm run check:contracts`. Exits non-zero on violation.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dirname ?? ".", "..");
+
+/**
+ * Files that must not import any specific adapter directly. Matches the
+ * list in docs/multi-agent-runtime-generalization-plan.md §32.2.1.
+ */
+const CORE_FILES = [
+  "src/services/instance-manager.ts",
+  "src/services/nomad-manager.ts",
+  "src/services/setup-manager.ts",
+  "src/services/backup-manager.ts",
+  "src/services/llm-proxy/index.ts",
+  "src/routes/instances.ts",
+  "src/routes/setup.ts",
+  "src/server.ts",
+] as const;
+
+/**
+ * Regexes for forbidden adapter imports. Covers both static imports and
+ * dynamic `import()`. Note: we deliberately allow references to the
+ * registry / runtime/index (`./runtime/index.js`, `./runtime/registry.js`,
+ * `./runtime/types.js`, `./runtime/instance.js`) because those contain
+ * the framework surface, not adapter-specific logic.
+ */
+const FORBIDDEN_IMPORT_PATTERNS = [
+  /from\s+["'][^"']*\/runtime\/adapters\/[^"']+["']/g,
+  /import\s*\(\s*["'][^"']*\/runtime\/adapters\/[^"']+["']\s*\)/g,
+];
+
+/**
+ * Literal strings that indicate kind-specific bleed-through into
+ * framework files. These are advisory only for now: existing OpenClaw
+ * legacy code may still contain OPENCLAW_HOME env references etc. We log
+ * them but don't fail the build — the physical migration cleans them up
+ * in a follow-up PR. When MIGRATION_STRICT=1 is set, they become errors.
+ */
+const KIND_LITERAL_PATTERNS: Array<{ pattern: RegExp; description: string }> = [
+  {
+    pattern: /JOB_PREFIX\s*=\s*["']openclaw-/,
+    description: `JOB_PREFIX literal "openclaw-" — §32.2.7 wants panel.nomadJobPrefix`,
+  },
+  {
+    pattern: /OPENCLAW_HOME|OPENCLAW_INSTANCE_ID|OPENCLAW_GATEWAY_PORT/,
+    description: `OpenClaw-specific env var literal — should live in OpenClawAdapter`,
+  },
+  {
+    pattern: /isHermesInstance\s*\(/,
+    description: `isHermesInstance() — runtime-specific branch, should dispatch via getAdapter`,
+  },
+  {
+    pattern: /agentType\s*===\s*["']hermes["']|agentType\s*===\s*["']openclaw["']/,
+    description: `agentType literal comparison — dispatch through adapter instead`,
+  },
+];
+
+const STRICT = process.env.MIGRATION_STRICT === "1";
+
+type Violation = {
+  file: string;
+  line: number;
+  column: number;
+  text: string;
+  rule: string;
+};
+
+function isCommentLine(lineText: string): boolean {
+  const t = lineText.trimStart();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*");
+}
+
+function findViolations(filepath: string, content: string): Violation[] {
+  const violations: Violation[] = [];
+
+  // 1. Forbidden adapter imports (HARD errors)
+  for (const pattern of FORBIDDEN_IMPORT_PATTERNS) {
+    let match: RegExpExecArray | null;
+    const re = new RegExp(pattern.source, "g");
+    while ((match = re.exec(content)) !== null) {
+      const before = content.slice(0, match.index);
+      const line = before.split("\n").length;
+      const column = match.index - before.lastIndexOf("\n");
+      violations.push({
+        file: filepath,
+        line,
+        column,
+        text: match[0],
+        rule: "adapter-import-forbidden",
+      });
+    }
+  }
+
+  // 2. Kind-specific literals (SOFT warnings unless MIGRATION_STRICT=1).
+  //    Comment lines are skipped — references in docstrings or `§32`
+  //    migration notes are not actual code bleed-through.
+  if (STRICT) {
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const lineText = lines[i];
+      if (isCommentLine(lineText)) continue;
+      for (const { pattern, description } of KIND_LITERAL_PATTERNS) {
+        if (pattern.test(lineText)) {
+          violations.push({
+            file: filepath,
+            line: i + 1,
+            column: 1,
+            text: lineText.trim().slice(0, 120),
+            rule: `kind-literal: ${description}`,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ── Fixture schema checks (plan §30.3) ───────────────────────────────
+//
+// Keep the schema rules inline: we only validate a handful of fields and
+// pulling in ajv for a single static script adds disproportionate churn.
+// The check mirrors the runtime contract in `runtime/migrations.ts`:
+//   - every meta must carry `id` / `name`
+//   - `agentType` resolves (missing → defaults to "openclaw")
+//   - Hermes fixtures must declare `paths.agentHome` + `paths.primaryConfig`
+//   - legacy openclaw fixtures must backfill to `agentType === "openclaw"`
+
+type FixtureViolation = { fixture: string; rule: string; detail: string };
+
+function resolveFixtureAgentType(meta: Record<string, unknown>): string {
+  const raw = typeof meta.agentType === "string" ? meta.agentType : "";
+  return raw.trim() ? raw.trim() : "openclaw";
+}
+
+function checkFixture(fixtureName: string, meta: Record<string, unknown>): FixtureViolation[] {
+  const out: FixtureViolation[] = [];
+  const agentType = resolveFixtureAgentType(meta);
+  if (typeof meta.id !== "string" || !meta.id) {
+    out.push({ fixture: fixtureName, rule: "missing-id", detail: "instance.json must carry a non-empty string id" });
+  }
+  if (typeof meta.name !== "string" || !meta.name) {
+    out.push({ fixture: fixtureName, rule: "missing-name", detail: "instance.json must carry a non-empty string name" });
+  }
+  if (agentType === "hermes") {
+    const paths = (meta.paths ?? {}) as Record<string, unknown>;
+    for (const key of ["agentHome", "primaryConfig", "secretEnv"] as const) {
+      if (typeof paths[key] !== "string" || !paths[key]) {
+        out.push({
+          fixture: fixtureName,
+          rule: `hermes-paths-${key}`,
+          detail: `hermes instance.json requires paths.${key}`,
+        });
+      }
+    }
+  }
+  if (fixtureName.startsWith("legacy-openclaw") && agentType !== "openclaw") {
+    out.push({
+      fixture: fixtureName,
+      rule: "legacy-backfill",
+      detail: `legacy fixture must backfill to agentType="openclaw", got "${agentType}"`,
+    });
+  }
+  return out;
+}
+
+function loadFixtures(): FixtureViolation[] {
+  const fixturesRoot = resolve(REPO_ROOT, "scripts/fixtures/instances");
+  let entries: string[];
+  try {
+    entries = readdirSync(fixturesRoot);
+  } catch {
+    return []; // directory optional during early migrations
+  }
+  const violations: FixtureViolation[] = [];
+  for (const entry of entries) {
+    const fullPath = resolve(fixturesRoot, entry);
+    try {
+      if (!statSync(fullPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const metaPath = resolve(fullPath, "instance.json");
+    let raw: string;
+    try {
+      raw = readFileSync(metaPath, "utf-8");
+    } catch {
+      violations.push({ fixture: entry, rule: "missing-instance-json", detail: metaPath });
+      continue;
+    }
+    try {
+      const meta = JSON.parse(raw) as Record<string, unknown>;
+      violations.push(...checkFixture(entry, meta));
+    } catch (e: any) {
+      violations.push({ fixture: entry, rule: "invalid-json", detail: e?.message ?? String(e) });
+    }
+  }
+  return violations;
+}
+
+function main(): void {
+  const allViolations: Violation[] = [];
+  const softFindings: Array<{ file: string; line: number; text: string; description: string }> = [];
+
+  for (const relPath of CORE_FILES) {
+    const abs = resolve(REPO_ROOT, relPath);
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      console.warn(`[check-adapter-isolation] skip (not found): ${relPath}`);
+      continue;
+    }
+    allViolations.push(...findViolations(relPath, content));
+
+    // Collect soft findings separately so non-strict runs can still report them.
+    if (!STRICT) {
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const lineText = lines[i];
+        if (isCommentLine(lineText)) continue;
+        for (const { pattern, description } of KIND_LITERAL_PATTERNS) {
+          if (pattern.test(lineText)) {
+            softFindings.push({
+              file: relPath,
+              line: i + 1,
+              text: lineText.trim().slice(0, 120),
+              description,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  const fixtureViolations = loadFixtures();
+
+  if (allViolations.length === 0 && softFindings.length === 0 && fixtureViolations.length === 0) {
+    console.log("[check-adapter-isolation] OK — core files are fully decoupled from specific adapters");
+    process.exit(0);
+  }
+
+  if (allViolations.length > 0) {
+    console.error(`\n[check-adapter-isolation] ${allViolations.length} HARD violation(s):\n`);
+    for (const v of allViolations) {
+      console.error(`  ${v.file}:${v.line}:${v.column}  [${v.rule}]`);
+      console.error(`    ${v.text}`);
+    }
+  }
+
+  if (fixtureViolations.length > 0) {
+    console.error(`\n[check-adapter-isolation] ${fixtureViolations.length} fixture violation(s):\n`);
+    for (const v of fixtureViolations) {
+      console.error(`  fixtures/${v.fixture}  [${v.rule}] ${v.detail}`);
+    }
+  }
+
+  if (softFindings.length > 0) {
+    console.warn(
+      `\n[check-adapter-isolation] ${softFindings.length} soft finding(s) (remaining framework bleed-through — migrate in follow-up PRs; run with MIGRATION_STRICT=1 to fail on these):\n`,
+    );
+    for (const f of softFindings) {
+      console.warn(`  ${f.file}:${f.line}  ${f.description}`);
+      console.warn(`    ${f.text}`);
+    }
+  }
+
+  process.exit(allViolations.length > 0 || fixtureViolations.length > 0 ? 1 : 0);
+}
+
+main();

package/scripts/fixtures/instances/hermes-sample/instance.json

@@ -0,0 +1,37 @@
+{
+  "id": "hermes-sample",
+  "name": "Hermes Sample",
+  "description": "Fixture for plan §30.3 contract check",
+  "agentType": "hermes",
+  "paths": {
+    "instanceDir": "/tmp/instances/hermes-sample",
+    "agentHome": "/tmp/instances/hermes-sample/agent-home",
+    "primaryConfig": "/tmp/instances/hermes-sample/agent-home/config.yaml",
+    "secretEnv": "/tmp/instances/hermes-sample/agent-home/.env"
+  },
+  "runtime": {
+    "driver": "docker",
+    "image": "ghcr.io/x-aijishu/hermes-runtime:latest",
+    "envFiles": ["/tmp/instances/hermes-sample/agent-home/.env"],
+    "ports": [
+      { "name": "gateway", "containerPort": 8642, "hostPort": 8642 }
+    ]
+  },
+  "x-jishushell": {
+    "proxy": {
+      "upstream": {
+        "providerId": "openai",
+        "baseUrl": "https://api.openai.com",
+        "api": "openai-completions",
+        "authHeader": false,
+        "headers": {},
+        "models": [{ "id": "gpt-4o-mini", "name": "gpt-4o-mini", "contextWindow": 128000 }],
+        "selectedModelId": "gpt-4o-mini",
+        "apiKey": "",
+        "hasApiKey": false,
+        "clearApiKey": false
+      }
+    }
+  },
+  "created_at": "2026-04-20T00:00:00.000Z"
+}

package/scripts/fixtures/instances/legacy-openclaw-sample/instance.json

@@ -0,0 +1,7 @@
+{
+  "id": "legacy-openclaw-sample",
+  "name": "Legacy OpenClaw",
+  "description": "Pre-§32.2 instance: no agentType, only openclaw_home. Must backfill to agentType=openclaw.",
+  "openclaw_home": "/tmp/instances/legacy-openclaw-sample/openclaw-home",
+  "created_at": "2025-11-01T00:00:00.000Z"
+}

package/scripts/smoke/hermes-bootstrap.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+#
+# End-to-end smoke for Hermes default onboarding.
+#
+# Drives the complete lifecycle against a running jishushell panel:
+#   1. install Hermes runtime (docker pull + shim + panel.json catalog)
+#   2. create a Hermes instance via POST /api/instances {"agentType":"hermes"}
+#   3. start the instance
+#   4. poll /health until 200 OK (or timeout)
+#   5. stop + delete the instance
+#   6. verify instance dir is cleaned up
+#
+# Usage:
+#   JISHUSHELL_URL=http://pi2:8090 JISHUSHELL_TOKEN=... ./scripts/smoke/hermes-bootstrap.sh
+#   (or run on the same host with defaults)
+#
+# Per docs/feedback_validate_before_commit.md, this script MUST be run on a
+# real Pi2 box before the Hermes onboarding work is considered complete.
+
+set -eo pipefail
+
+PANEL_URL="${JISHUSHELL_URL:-http://127.0.0.1:8090}"
+AUTH_TOKEN="${JISHUSHELL_TOKEN:-}"
+INSTANCE_ID="${INSTANCE_ID:-hermes-smoke}"
+INSTANCE_NAME="${INSTANCE_NAME:-Hermes Smoke Test}"
+HEALTH_TIMEOUT="${HEALTH_TIMEOUT:-180}" # seconds; first docker pull can take a while
+INSTALL_TIMEOUT="${INSTALL_TIMEOUT:-1800}" # 30 min for 2.4 GB image on slow links
+
+red()   { printf '\033[31m%s\033[0m\n' "$*"; }
+green() { printf '\033[32m%s\033[0m\n' "$*"; }
+blue()  { printf '\033[34m%s\033[0m\n' "$*"; }
+yellow(){ printf '\033[33m%s\033[0m\n' "$*"; }
+
+log()  { blue  "[hermes-smoke] $*"; }
+ok()   { green "[hermes-smoke] ✔ $*"; }
+fail() { red   "[hermes-smoke] ✘ $*"; exit 1; }
+
+CURL_AUTH=()
+if [ -n "$AUTH_TOKEN" ]; then
+  CURL_AUTH=(-H "Authorization: Bearer $AUTH_TOKEN")
+fi
+
+api() {
+  local method="$1"; shift
+  local path="$1"; shift
+  curl -fsS -X "$method" "${PANEL_URL}${path}" \
+    "${CURL_AUTH[@]}" \
+    -H "Content-Type: application/json" \
+    "$@"
+}
+
+# ── 0. Preflight ──────────────────────────────────────────────────────
+
+log "panel: $PANEL_URL"
+log "instance: $INSTANCE_ID"
+
+if ! curl -fsS "$PANEL_URL/api/setup/status" "${CURL_AUTH[@]}" >/dev/null 2>&1; then
+  fail "panel not reachable at $PANEL_URL"
+fi
+ok "panel reachable"
+
+# Ensure any stale instance from a prior run is gone
+if curl -fsS "$PANEL_URL/api/instances/$INSTANCE_ID" "${CURL_AUTH[@]}" >/dev/null 2>&1; then
+  yellow "stale $INSTANCE_ID found, cleaning up first"
+  api DELETE "/api/instances/$INSTANCE_ID?purge_backups=true" >/dev/null || true
+  sleep 2
+fi
+
+# ── 1. Install Hermes runtime ────────────────────────────────────────
+
+log "installing Hermes runtime (this pulls ~2.4 GB on first run)..."
+INSTALL_RESP=$(api POST "/api/setup/install/hermes" -d '{}')
+TASK_ID=$(printf '%s' "$INSTALL_RESP" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('taskId',''))" 2>/dev/null || echo "")
+if [ -z "$TASK_ID" ]; then
+  fail "installHermes did not return a taskId. Response: $INSTALL_RESP"
+fi
+log "install task: $TASK_ID — polling..."
+
+START_TS=$(date +%s)
+while : ; do
+  STATUS_RESP=$(curl -fsS "$PANEL_URL/api/setup/tasks/$TASK_ID" "${CURL_AUTH[@]}")
+  STATUS=$(printf '%s' "$STATUS_RESP" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('status',''))" 2>/dev/null || echo "")
+  LAST_MSG=$(printf '%s' "$STATUS_RESP" | python3 -c "import json,sys; d=json.load(sys.stdin); ev=d.get('events') or []; print(ev[-1].get('message','')) if ev else print('')" 2>/dev/null || echo "")
+  ELAPSED=$(( $(date +%s) - START_TS ))
+  printf '\r  [%ds] %-60s' "$ELAPSED" "$LAST_MSG"
+  if [ "$STATUS" = "done" ]; then
+    printf '\n'
+    ok "Hermes installed"
+    break
+  fi
+  if [ "$STATUS" = "error" ]; then
+    printf '\n'
+    fail "Hermes install failed: $LAST_MSG"
+  fi
+  if [ "$ELAPSED" -gt "$INSTALL_TIMEOUT" ]; then
+    printf '\n'
+    fail "Hermes install timeout after ${INSTALL_TIMEOUT}s"
+  fi
+  sleep 3
+done
+
+# ── 2. Create Hermes instance ────────────────────────────────────────
+
+log "creating instance $INSTANCE_ID..."
+CREATE_BODY=$(printf '{"id":"%s","name":"%s","agentType":"hermes"}' "$INSTANCE_ID" "$INSTANCE_NAME")
+CREATE_RESP=$(api POST "/api/instances" -d "$CREATE_BODY")
+AGENT_TYPE=$(printf '%s' "$CREATE_RESP" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('agentType',''))" 2>/dev/null || echo "")
+if [ "$AGENT_TYPE" != "hermes" ]; then
+  fail "created instance has wrong agentType: expected 'hermes', got '$AGENT_TYPE'. Response: $CREATE_RESP"
+fi
+ok "instance created"
+
+# ── 3. Start (may already be auto-started if default_provider is set) ─
+
+log "starting instance..."
+api POST "/api/instances/$INSTANCE_ID/service/start" -d '{}' >/dev/null || yellow "service/start returned non-2xx (may already be running)"
+
+# ── 4. Poll /health ──────────────────────────────────────────────────
+
+log "resolving allocated host port..."
+sleep 3
+GW_INFO=$(api GET "/api/instances/$INSTANCE_ID/gateway-launch" 2>/dev/null || echo "")
+GW_PORT=$(printf '%s' "$GW_INFO" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('port',''))" 2>/dev/null || echo "")
+if [ -z "$GW_PORT" ]; then
+  # Fallback: read port from instance.json via /api/instances/:id
+  INST_INFO=$(api GET "/api/instances/$INSTANCE_ID")
+  GW_PORT=$(printf '%s' "$INST_INFO" | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+rt = d.get('runtime', {}) or {}
+ports = rt.get('ports') or []
+for p in ports:
+    if p.get('name') == 'gateway':
+        print(p.get('hostPort', ''))
+        break
+else:
+    print('')
+" 2>/dev/null || echo "")
+fi
+if [ -z "$GW_PORT" ] || [ "$GW_PORT" = "0" ]; then
+  fail "could not resolve allocated gateway port"
+fi
+log "gateway port: $GW_PORT"
+
+# Determine health target — assume panel host for Pi deploy
+HEALTH_HOST=$(printf '%s' "$PANEL_URL" | sed -E 's#https?://([^:/]+).*#\1#')
+HEALTH_URL="http://${HEALTH_HOST}:${GW_PORT}/health"
+log "probing $HEALTH_URL (timeout ${HEALTH_TIMEOUT}s)..."
+
+START_TS=$(date +%s)
+while : ; do
+  if BODY=$(curl -fsS --max-time 5 "$HEALTH_URL" 2>/dev/null); then
+    STATUS_FIELD=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('status',''))" 2>/dev/null || echo "")
+    PLATFORM=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('platform',''))" 2>/dev/null || echo "")
+    if [ "$STATUS_FIELD" = "ok" ] && [ "$PLATFORM" = "hermes-agent" ]; then
+      ok "health OK — ${BODY}"
+      break
+    fi
+  fi
+  ELAPSED=$(( $(date +%s) - START_TS ))
+  if [ "$ELAPSED" -gt "$HEALTH_TIMEOUT" ]; then
+    red "   last body: $BODY"
+    fail "health check timeout after ${HEALTH_TIMEOUT}s"
+  fi
+  printf '\r  [%ds] waiting for /health ... ' "$ELAPSED"
+  sleep 3
+done
+
+# ── 5. Stop + delete ─────────────────────────────────────────────────
+
+log "stopping instance..."
+api POST "/api/instances/$INSTANCE_ID/service/stop" -d '{}' >/dev/null
+ok "stopped"
+
+log "deleting instance..."
+api DELETE "/api/instances/$INSTANCE_ID?purge_backups=true" >/dev/null
+ok "deleted"
+
+# ── 6. Verify cleanup ────────────────────────────────────────────────
+
+# Via API — should 404
+if curl -fsS "$PANEL_URL/api/instances/$INSTANCE_ID" "${CURL_AUTH[@]}" >/dev/null 2>&1; then
+  fail "instance still exists after delete"
+fi
+ok "instance removed from panel"
+
+# Via filesystem — optional local verification (works when running on same host)
+if [ -d "$HOME/.jishushell/instances/$INSTANCE_ID" ]; then
+  fail "instance directory still exists at $HOME/.jishushell/instances/$INSTANCE_ID"
+fi
+
+green ""
+green "════════════════════════════════════════════"
+green " Hermes default onboarding smoke: PASSED"
+green "════════════════════════════════════════════"