zelpi 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# ZelPi — `zos` CLI
+
+**ZelPi** (Physical Intelligence Operating System) as an `npm install`-able,
+self-contained command-line OS for autonomous robot fleets.
+
+```bash
+npm install -g pios     # installs the `zos` command
+zos                     # interactive OS shell — boots a backend automatically
+```
+
+No repo, no database, no API keys required: the package ships a **bundled
+simulation engine** and an **embedded backend** that auto-starts on first use.
+Point it at a real ZelPi backend later with one env var.
+
+It implements the "AI Integration for Embedded" architecture as a top-to-bottom
+command surface:
+
+```
+CLI / REPL              bin + cli/repl          ← top layer
+   │
+MCP / API Hooks         cli/client · cli/mcp     ← agents (north) + backend (south)
+   │
+Kernel — QoS router     cli/kernel + engine      ← Robustness | Optimisation | System-Critical
+   │
+Model layer (VLM·WM·VLA·LLM)   models train/deploy
+   │
+Cloud (train/store)     hub pull · models train
+   │
+Hub / Repo (SOCs · HF)  cli/hub                  ← compatible SOCs + HuggingFace registry
+```
+
+## Quick start
+
+```bash
+zos                                  # OS shell (auto-starts the embedded backend)
+zos status                           # health · profile · fleet · deployed models
+zos intent "Inventory Aisle 4"       # natural-language intent → System-2 plan → dispatch
+zos profile optimisation             # switch the kernel QoS profile
+zos hub pull openvla/openvla-7b      # load a model from HuggingFace
+zos models deploy M4                 # promote a trained model to the fleet
+zos watch                            # live activity feed
+zos down                             # stop the embedded backend daemon
+```
+
+Bare text in the shell is treated as an intent, so `zos` feels like a
+conversational OS console.
+
+## How it runs
+
+- **Embedded (default).** Any command auto-starts a local backend (`cli/embedded.mjs`)
+  running the bundled engine over the same WS+HTTP protocol the full ZelPi server
+  speaks. State persists to `~/.pi-os/embedded-state.json`. Intent parsing is the
+  deterministic offline parser (no keys). `zos up` runs it in the foreground;
+  `zos down` stops the daemon.
+- **Connected.** Point at a full backend (with a live LLM, ROS, MLflow, auth):
+
+  ```bash
+  export PIOS_HOST=http://your-host:8787
+  export PIOS_WS_URL=ws://your-host:8787
+  zos status
+  # or persist:  zos config set host your-host && zos config set port 8787
+  ```
+
+## The Kernel — QoS profile router
+
+Every intent is routed through one execution profile; the engine applies it,
+biasing **Safety-Broker scrutiny** and **execution speed**.
+
+| Profile | Speed | Safety gating | Use |
+|---|---|---|---|
+| `balanced` | nominal | nominal | kernel default |
+| `robustness` | −5% | +20% | many SOCs/buses, multi-system spread |
+| `optimisation` | +40% | −50% | fast routine tasks, speed > deliberation |
+| `system-critical` | −18% | +80% | precise, high-integrity work |
+
+```bash
+zos profile                       # list + active
+zos profile system-critical
+zos intent "Retrieve the green box from Aisle 3" --profile system-critical
+```
+
+## Commands
+
+```
+status                          backend health, profile, fleet, deployed models
+intent "<text>" [--profile p]   submit a natural-language intent
+safety [authorize|reroute|abort] show / resolve the Human-in-the-Loop gate
+watch                           stream the live activity feed
+pause | resume | reset          fleet lifecycle
+
+profile [name]                  kernel QoS router
+
+fleet                           list robots
+fleet enroll --chassis "<c>" [--name <n>] [--aisle <n>]
+
+models                          model registry (vla→S2, act→S1, mhal→S0)
+models train --kind vla|act|mhal [--name <n>] [--embodiment <e>]
+models deploy <id>
+
+hub [socs|chassis|models]       compatible SOCs, embodiments, model registry
+hub pull <key|hf-id>            load a model from HF (e.g. pi0, openvla/openvla-7b)
+
+up [--ros] [--force] [--embedded]   boot a backend
+down                            stop the embedded backend daemon
+mcp                             run the MCP server (expose ZelPi to AI agents over stdio)
+login [user]                    fetch + store a dev JWT
+metrics                         Prometheus exposition
+config [set <key> <value>]      backend host/port/token
+```
+
+## MCP — drive the fleet from an AI agent
+
+`zos mcp` runs a Model-Context-Protocol server over stdio (JSON-RPC 2.0). Tools:
+`pios_status`, `pios_intent`, `pios_set_profile`, `pios_fleet`, `pios_models`,
+`pios_deploy_model`, `pios_resolve_safety`, `pios_hub`.
+
+```json
+{
+  "mcpServers": {
+    "pi-os": { "command": "zos", "args": ["mcp"], "env": { "PIOS_HOST": "http://127.0.0.1:8787" } }
+  }
+}
+```
+
+## Environment
+
+| Var | Meaning |
+|---|---|
+| `PIOS_HOST` | backend HTTP base (e.g. `http://10.0.0.5:8787`) |
+| `PIOS_WS_URL` | backend WS base |
+| `PIOS_TOKEN` | JWT for an auth-enabled backend (`zos login` fetches a dev token) |
+| `PIOS_NO_AUTOSTART` | disable embedded auto-start |
+| `NO_COLOR` | disable ANSI color |
+
+Config persists to `~/.pi-os/config.json`.
+
+## Publishing (maintainers)
+
+The publishable package is assembled from this repo into `cli-dist/` — lean
+(only `ws`), self-contained (bundled engine), free of the web-app deps.
+
+```bash
+npm run build:pkg              # → cli-dist/  (esbuild bundle + cli/ + bin/ + package.json)
+cd cli-dist
+npm publish --access public    # requires `npm login`
+```
+
+Requires Node ≥ 18 (uses the global WebSocket client on Node 21+, falls back to
+`ws` on older runtimes).

package/bin/pi-os.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// pi-os — Physical Intelligence Operating System · CLI entrypoint.
+// `npm install -g .` (or `npm link`) exposes this as the `pi-os` command.
+// No args → interactive OS shell. Otherwise dispatch a single command.
+
+import { run, NO_AUTOSTART } from "../cli/dispatch.mjs";
+import { repl } from "../cli/repl.mjs";
+import { ensureBackend } from "../cli/daemon.mjs";
+import { HELP } from "../cli/help.mjs";
+import { c, sym } from "../cli/ui.mjs";
+
+const argv = process.argv.slice(2);
+const first = argv[0];
+
+async function main() {
+  if (first === "help" || first === "--help" || first === "-h") return console.log(HELP);
+  if (first === "version" || first === "--version" || first === "-v") {
+    const { createRequire } = await import("node:module");
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json");
+    return console.log(`zelpi ${pkg.version}`);
+  }
+  // Interactive OS shell.
+  if (!first || first === "shell") {
+    await ensureBackend().catch(() => {});
+    return repl();
+  }
+  // For commands that talk to the backend, make sure one is up (auto-start the
+  // self-contained embedded backend for local targets — the npm-install path).
+  if (!NO_AUTOSTART.has(first)) await ensureBackend().catch(() => {});
+  await run(argv);
+}
+
+main().catch((e) => {
+  console.error(`${sym.err} ${c.red(e.message || String(e))}`);
+  process.exit(1);
+});

package/cli/client.mjs

@@ -0,0 +1,148 @@
+// pi-os CLI — API Hooks layer.
+// The southbound connection from the CLI to the ZelPi backend: HTTP for health /
+// DB views / metrics, and a WebSocket for the live command + snapshot channel
+// (the same protocol the web console speaks). Uses Node's built-in fetch +
+// global WebSocket — zero dependencies.
+
+import { httpBase, wsUrl, load } from "./config.mjs";
+
+class PiosError extends Error {}
+
+// Prefer Node's global WebSocket client (Node 21+/22+); fall back to the `ws`
+// package on older runtimes so the published package works broadly.
+let _WS = globalThis.WebSocket;
+async function WSClass() {
+  if (!_WS) _WS = (await import("ws")).WebSocket;
+  return _WS;
+}
+
+async function getJSON(pathname) {
+  const base = httpBase();
+  let res;
+  try {
+    res = await fetch(base + pathname, { signal: AbortSignal.timeout(5000) });
+  } catch (e) {
+    throw new PiosError(`backend unreachable at ${base} (${e.code || e.name}). Is it running? Try: npx zelpi up`);
+  }
+  if (!res.ok) throw new PiosError(`${pathname} → HTTP ${res.status}`);
+  const txt = await res.text();
+  try {
+    return JSON.parse(txt);
+  } catch {
+    return txt;
+  }
+}
+
+export const health = () => getJSON("/health");
+export const dbTasks = () => getJSON("/db/tasks");
+export const dbModels = () => getJSON("/db/models");
+export const dbEmbodiments = () => getJSON("/db/embodiments");
+export const metricsText = () => getJSON("/metrics");
+
+export async function login(user = "operator") {
+  const base = httpBase();
+  const res = await fetch(base + "/auth/login", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ user }),
+  });
+  return res.json();
+}
+
+/** Open a WS, run `fn(ws)` once connected, and resolve when `done()` is called. */
+function withSocket(fn, { timeout = 8000 } = {}) {
+  return new Promise(async (resolve, reject) => {
+    let ws;
+    try {
+      const WS = await WSClass();
+      ws = new WS(wsUrl());
+    } catch (e) {
+      return reject(new PiosError(`could not open socket: ${e.message}`));
+    }
+    const timer = setTimeout(() => {
+      try { ws.close(); } catch {}
+      reject(new PiosError(`timed out talking to backend (${wsUrl()})`));
+    }, timeout);
+    let result;
+    const done = (value) => {
+      result = value;
+      clearTimeout(timer);
+      try { ws.close(); } catch {}
+    };
+    ws.addEventListener("open", () => {
+      try { fn(ws, done); } catch (e) { clearTimeout(timer); reject(e); }
+    });
+    ws.addEventListener("close", (e) => {
+      clearTimeout(timer);
+      if (e && e.code === 1008) return reject(new PiosError("unauthorized — set a token: npx zelpi login"));
+      resolve(result);
+    });
+    ws.addEventListener("error", () => {
+      clearTimeout(timer);
+      reject(new PiosError(`socket error connecting to ${wsUrl()}. Is the backend up?`));
+    });
+  });
+}
+
+const parse = (data) => {
+  try { return JSON.parse(typeof data === "string" ? data : data.toString()); } catch { return null; }
+};
+
+/** Fetch a single live snapshot over the WS channel. */
+export function snapshot() {
+  return withSocket((ws, done) => {
+    ws.addEventListener("message", (e) => {
+      const m = parse(e.data);
+      if (m && m.type === "snapshot") done(m.snap);
+    });
+  });
+}
+
+/**
+ * Send one command and read back its effect. By default wait `settle` snapshots;
+ * if an `until(snap)` predicate is given, resolve on the first post-command
+ * snapshot that satisfies it (or after `timeout` ms) — needed for effects that
+ * complete asynchronously server-side, e.g. an LLM-planned intent.
+ */
+export function command(msg, { settle = 0, until = null, timeout = 8000 } = {}) {
+  return withSocket(
+    (ws, done) => {
+      let sent = false;
+      ws.addEventListener("message", (e) => {
+        const m = parse(e.data);
+        if (!m || m.type !== "snapshot") return;
+        if (!sent) {
+          // ignore the immediate pre-command snapshot, then send
+          sent = true;
+          ws.send(JSON.stringify(msg));
+          if (!until && settle === 0) done(m.snap);
+          return;
+        }
+        if (until) { if (until(m.snap)) done(m.snap); }
+        else if (--settle <= 0) done(m.snap);
+      });
+    },
+    { timeout },
+  );
+}
+
+/** Stream snapshots to `onSnap` until the returned stop() is called. */
+export function watch(onSnap) {
+  let socket;
+  let stopped = false;
+  const open = async () => {
+    const WS = await WSClass();
+    if (stopped) return;
+    socket = new WS(wsUrl());
+    socket.addEventListener("message", (e) => {
+      const m = parse(e.data);
+      if (m && m.type === "snapshot") onSnap(m.snap);
+    });
+    socket.addEventListener("close", () => { if (!stopped) setTimeout(open, 1000); });
+    socket.addEventListener("error", () => { try { socket.close(); } catch {} });
+  };
+  open();
+  return () => { stopped = true; try { socket.close(); } catch {} };
+}
+
+export { PiosError, load };