@jmcombs/pi-steward 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Combs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/steward/preview.png" width="250" alt="@jmcombs/pi-steward">
+  <br>
+  <a href="https://www.npmjs.com/package/@jmcombs/pi-steward"><img src="https://img.shields.io/npm/v/@jmcombs/pi-steward.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@jmcombs/pi-steward"><img src="https://img.shields.io/npm/dm/@jmcombs/pi-steward.svg" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/jmcombs/pi-extensions/stargazers"><img src="https://img.shields.io/github/stars/jmcombs/pi-extensions?style=social" alt="GitHub stars"></a>
+  <a href="https://github.com/jmcombs/pi-extensions/issues"><img src="https://img.shields.io/github/issues/jmcombs/pi-extensions" alt="Open issues"></a>
+  <a href="https://github.com/sponsors/jmcombs"><img src="https://img.shields.io/badge/Sponsor-30363D?style=flat&logo=GitHub-Sponsors&logoColor=EA4AAA" alt="Sponsor"></a>
+</div>
+
+# @jmcombs/pi-steward
+
+> **Steward — the llama.cpp control panel for [Pi](https://pi.dev).** *How may we serve your models?*
+
+A single-page operator dashboard for the local `llama-server` behind Pi's llama.cpp provider, plus a
+status bar inside Pi itself. It answers four questions at a glance, and lets you act on all of them
+without leaving your editor:
+
+1. **Is the service up**, and for how long?
+2. **Which models are resident**, and what is each costing you in memory?
+3. **Is the box healthy** — GPU, CPU, memory, temperature?
+4. **What is the server doing right now** — slots, throughput, requests, and its live log?
+
+Start, stop and restart the service; load and unload models; watch the log — all from the dashboard.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/steward/dashboard.png" width="900" alt="The Steward dashboard">
+</div>
+
+## Requirements
+
+| | |
+| --- | --- |
+| **Node** | ≥ 22.13 |
+| **[Pi](https://pi.dev)** | any recent version |
+| **`llama-server`** | running in **router mode** — `--models-dir` and/or `--models-preset`, with no `-m`/`--model`/`-hf`. Pi's own llama.cpp provider requires this too. |
+| **A [Nerd Font](https://www.nerdfonts.com)** | for the status bar's mark and separators. Set `STEWARD_GLYPH=""` to drop the mark if you would rather not install one. |
+
+`/steward_initialize` checks everything else — metrics, slots, log capture, host sensors — and offers
+to fix whatever is missing.
+
+## Install
+
+```bash
+# Globally (recommended)
+pi install npm:@jmcombs/pi-steward
+
+# For a single session, without installing
+pi -e ./packages/steward
+```
+
+See the [Pi packages documentation](https://pi.dev/docs/packages) for git, local path,
+project-scoped install, and filtering options.
+
+## Quick start
+
+Start Pi, then:
+
+```
+/steward_initialize     1. connect this machine — review, approve, done
+/steward_start          2. start the dashboard service
+/steward_dashboard      3. open it in your browser
+```
+
+That is the whole path. Step 1 is once per machine; steps 2 and 3 are once per session — and
+`/steward_dashboard` starts the service for you, so you can skip straight to it.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/steward_initialize` | Connects this machine to Steward. Works out how `llama-server` runs here, proposes the changes it needs, and writes `steward.json` — **asking before every change**. Run once per machine, or again whenever the setup moves. |
+| `/steward_start` | Starts the dashboard service on `127.0.0.1:8788` for this session. Prints the URL and opens nothing — useful on a headless box, or when you only want the status bar. |
+| `/steward_dashboard` | Opens the dashboard in your browser, starting the service first if it is not already running. |
+| `/steward_stop` | Stops the dashboard service. It also stops on its own when the Pi session ends. |
+
+## The status bar
+
+Steward draws a line above the editor whenever it has something to say. It reports **Steward's own
+state** first, with `llama.cpp` as detail.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/steward/status-states.svg" width="620" alt="Steward status bar states">
+</div>
+
+- **Everything up** — the dashboard is on `:8788`, `llama.cpp` answers on `:8080`, and 1 of its 10
+  models is resident. The count is models holding weights in memory, not models on disk.
+- **llama.cpp down** — Steward is fine and says so in green; the server gets its own red block. The
+  dashboard still opens, and Start is there if you recorded one.
+- **Not read yet** — Steward is up but has not completed a read. Deliberately its own colour: an
+  absent reading is not a healthy one.
+- **Dashboard not running** — no `/steward_start` yet, or you stopped it. Nothing is said about
+  `llama.cpp`, because Steward is not watching it.
+- **Pointed elsewhere** — Pi is dialling a different address than the server Steward watches, so
+  chat fails while everything else looks healthy. The bar names the fix.
+
+Three colours, and only three: **green** started, **red** stopped, **orange** running but something
+needs a person.
+
+It refreshes while the dashboard is up, and reads the same data the dashboard does — no extra
+connection to your server.
+
+
+## Configuration
+
+Run `/steward_initialize` and let your clanker set me up. It reviews the local environment, captures
+how `llama.cpp` is currently configured, works out what is needed for Pi, Steward and `llama.cpp` to
+run together, then hands you a plan to approve. Nothing is applied before you say so.
+
+It writes `~/.config/steward/steward.json` at mode `0600` — the collector, the log path, the base
+URL, the service commands, and a consent hash for every command Steward may run. Steward ignores
+that file if it is not owned by you or is world-writable, because it is a code-execution surface.
+
+
+### Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `STEWARD_CONFIG` | `~/.config/steward/steward.json` | Where the artifact lives. |
+| `STEWARD_PORT` | `8788` | Dashboard port. `0` asks the OS for any free port; a port already taken costs an ephemeral one, not the dashboard. |
+| `STEWARD_LOG_FILE` | — | Overrides the recorded `log.path` for the log console. |
+| `STEWARD_GLYPH` | `󰢍` | The status bar's mark. `""` drops it; any other value replaces it. |
+
+
+## Development
+
+```bash
+# From the repo root
+npx vitest run packages/steward     # tests
+node scripts/typecheck.mjs          # types
+npx biome check packages/steward    # lint and format
+
+# Run the dashboard without Pi
+npx tsx packages/steward/scripts/dev.ts
+```
+
+## License
+
+MIT © [Jeremy Combs](https://github.com/jmcombs)

package/core/disconnected-source.ts

@@ -0,0 +1,110 @@
+/**
+ * The source Steward uses when it has nothing to read.
+ *
+ * This replaces the simulated source the dashboard used to fall back on. That
+ * fallback was a liability: a machine with no `steward.json`, or one whose
+ * `llama-server` could not be reached, rendered a complete, plausible, moving
+ * dashboard made entirely of invented numbers — indistinguishable from the real
+ * thing. It was observed serving three "loaded" models on a machine whose router
+ * had ten models and none loaded.
+ *
+ * Nothing here invents a reading. Every gauge is `NaN` (which the UI renders as
+ * a no-reading track, never a zero), every list is empty, drift is `unknown`
+ * with a reason, and the service reports itself not running with no controls.
+ * The panels go blank and say so, which is the only honest thing a dashboard can
+ * do about a machine it cannot see.
+ *
+ * Keep this module free of Node and DOM APIs — see `./types.ts`.
+ */
+
+import { unknownDrift } from "./drift.js";
+import type { LogAttachment, StewardDataSource, Unsubscribe } from "./source.js";
+import type { HostMetrics, LogLine, ModelAction, ServiceAction, Snapshot } from "./types.js";
+
+/** Why the dashboard has nothing to show, in the operator's vocabulary. */
+export const NOT_CONNECTED_REASON =
+  "Steward is not connected to this machine — run /steward_initialize";
+
+/**
+ * Every gauge as a no-reading. `NaN` is deliberate and load-bearing: the UI
+ * distinguishes it from `0`, so an unmeasured host reads as blank rather than as
+ * an idle one.
+ */
+function noReadings(): HostMetrics {
+  return {
+    vramUsedGB: Number.NaN,
+    vramTotalGB: Number.NaN,
+    ramUsedGB: Number.NaN,
+    ramTotalGB: Number.NaN,
+    gpuUtil: Number.NaN,
+    cpuUtil: Number.NaN,
+    gpuTempC: null,
+    cpuTempC: null,
+  };
+}
+
+/**
+ * A complete Snapshot that asserts nothing. `now` is the caller's clock so the
+ * dashboard's own staleness logic still works; everything else is absent.
+ */
+export function disconnectedSnapshot(now: number): Snapshot {
+  return {
+    now,
+    service: {
+      running: false,
+      startedAt: null,
+      pid: null,
+      host: "",
+      port: 0,
+      build: "",
+      controls: [],
+    },
+    models: [],
+    slots: [],
+    metrics: noReadings(),
+    memoryTopology: "unified",
+    drift: unknownDrift(NOT_CONNECTED_REASON),
+    throughputTps: null,
+    throughputWindowSeconds: null,
+    requestsInFlight: null,
+    throughputHistory: [],
+    requestsQueued: null,
+    config: [],
+  };
+}
+
+/** A source with no machine behind it. Every read is empty; every write refuses. */
+export function createDisconnectedSource(): StewardDataSource {
+  return {
+    name: "disconnected",
+
+    async snapshot(): Promise<Snapshot> {
+      return disconnectedSnapshot(Date.now());
+    },
+
+    recentLogs(): LogLine[] {
+      return [];
+    },
+
+    subscribeLogs(): Unsubscribe {
+      // Nothing will ever arrive, but the contract is a working unsubscribe.
+      return () => {};
+    },
+
+    attachLogs(): LogAttachment {
+      return { backlog: [], unsubscribe: () => {} };
+    },
+
+    // Refusing beats resolving: a caller that thinks a start succeeded here
+    // would poll forever for a service that was never asked to do anything.
+    async setService(action: ServiceAction): Promise<void> {
+      throw new Error(`cannot ${action} — ${NOT_CONNECTED_REASON}`);
+    },
+
+    async setModel(modelId: string, action: ModelAction): Promise<void> {
+      throw new Error(`cannot ${action} ${modelId} — ${NOT_CONNECTED_REASON}`);
+    },
+
+    close(): void {},
+  };
+}

package/core/drift.ts

@@ -0,0 +1,247 @@
+/**
+ * Config drift — the honesty check behind everything `steward.json` asserts.
+ *
+ * Steward's facts about a machine (which flags `llama-server` was launched
+ * with, which commands the operator approved) come from an artifact written
+ * once, by the `/steward_initialize` skill. Nothing stops the operator editing
+ * their launchd plist or systemd unit afterwards, and nothing announces it when
+ * they do. Without a re-check, a machine that lost `--metrics` shows a dark
+ * throughput tile AND — because "fully compliant renders nothing" — an implicit
+ * all-clear. This module is the type surface that makes the mismatch visible.
+ *
+ * Two independent producers feed one notice:
+ *   - {@link LaunchDrift}: the live process argv diffed against what was
+ *     recorded (the Node body that reads it lives in `server/drift-probe.ts`;
+ *     the comparison itself is {@link diffLaunchArgv}, here, so it is testable
+ *     without a real `llama-server`).
+ *   - {@link ConsentDrift}: a collector or control command `steward.json`
+ *     declares but whose exact command is NOT in the consent map. Today that
+ *     silently does nothing — no collector, no button — and the operator has no
+ *     way to tell an inert panel from an unconfigured one.
+ *
+ * The load-bearing rule for both: a check that could not be made is `unknown`,
+ * never a quiet "clean" and never a fabricated "drifted". A false alarm on a
+ * correctly configured machine costs exactly as much trust as a missed one.
+ *
+ * Keep this module free of Node and DOM APIs — see `./types.ts`.
+ */
+
+import type { ServiceAction } from "./types.js";
+
+/**
+ * The verdict of the launch-argv re-check.
+ *
+ * `unknown` is the honest degrade: no listening process, no `ps`, a permission
+ * error, a command line the process list truncated, or no recorded argv to
+ * compare against. It renders nothing, exactly as `clean` does — the difference
+ * is that `clean` is a statement and `unknown` is an absence of one.
+ */
+export type LaunchDriftStatus = "clean" | "drifted" | "unknown";
+
+/** The program path recorded at setup against the one running now. */
+export interface ProgramChange {
+  recorded: string;
+  observed: string;
+}
+
+/**
+ * How the running process's argv compares to the argv `/steward_initialize`
+ * recorded. `added` and `removed` are whole flag GROUPS (`--port 8080`, not two
+ * loose tokens), so the notice can name what actually changed rather than
+ * printing two command lines and leaving the operator to spot the difference.
+ */
+export interface LaunchDrift {
+  status: LaunchDriftStatus;
+  /** Groups the live process carries that were not recorded, e.g. `--no-slots`. */
+  added: string[];
+  /** Groups that were recorded and are gone now, e.g. `--metrics`. */
+  removed: string[];
+  /** Set when the binary itself changed; `null` when it did not. */
+  program: ProgramChange | null;
+  /** Why no verdict could be reached (`unknown` only); `null` otherwise. */
+  reason: string | null;
+}
+
+/**
+ * Commands `steward.json` declares but that carry no matching entry in its
+ * consent map. Steward refuses to run them — that is the security gate working
+ * — but silence makes the resulting empty panel indistinguishable from one that
+ * was never configured.
+ */
+export interface ConsentDrift {
+  /** True when a collector is declared and its exact command is unapproved. */
+  hostCollector: boolean;
+  /** Declared-but-unapproved control actions, in start/stop/restart order. */
+  controls: ServiceAction[];
+}
+
+/** Both producers, as carried on a {@link import("./types.js").Snapshot}. */
+export interface DriftState {
+  launch: LaunchDrift;
+  consent: ConsentDrift;
+}
+
+/**
+ * Re-validates the launch argv of one already-identified process. Node-side and
+ * platform-specific (it shells out to `ps`), so it is injected rather than
+ * imported by the source — this module stays free of Node APIs, mirroring
+ * {@link import("./llama-source.js").ServiceProbe}.
+ *
+ * It takes the pid the snapshot already resolved rather than a host and port,
+ * so the drift notice and the SERVICE block can never end up describing two
+ * different processes (and so a second `lsof` is not run per poll). A `null`
+ * pid — nothing listening, or no process probe configured — is a check that
+ * could not be made. It never rejects: every failure is an `unknown`
+ * {@link LaunchDrift}.
+ */
+export type DriftProbe = (pid: number | null) => Promise<LaunchDrift>;
+
+/** Nothing declared, nothing unapproved. */
+export const NO_CONSENT_DRIFT: ConsentDrift = { hostCollector: false, controls: [] };
+
+/** An "it could not be checked" verdict carrying the reason it could not. */
+export function unknownLaunchDrift(reason: string): LaunchDrift {
+  return { status: "unknown", added: [], removed: [], program: null, reason };
+}
+
+/** The drift state of a source that does not re-validate anything. */
+export function unknownDrift(reason: string): DriftState {
+  return { launch: unknownLaunchDrift(reason), consent: NO_CONSENT_DRIFT };
+}
+
+/**
+ * What `ps` prints when it has a process but no argv to show for it: a zombie,
+ * or a Linux `/proc` mounted with `hidepid`, comes back as `(llama-server)` or
+ * `[llama-server]`. It is a placeholder, not a command line — diffing against it
+ * would report every recorded flag removed AND a changed binary, the loudest
+ * possible false alarm on a machine that changed nothing.
+ */
+const PLACEHOLDER_COMMAND = /^\(.*\)$|^\[.*\]$/u;
+
+/**
+ * Splits an argv into flag groups: a token starting with `-` opens a group and
+ * every following non-flag token belongs to it, so `--port 8080` is one unit and
+ * `--metrics` is another. Tokens before the first flag are the program and its
+ * bare operands, returned separately — the binary changing is a different fact
+ * from a flag changing, and reads differently in the notice.
+ *
+ * `--flag=value` is normalised to `--flag value`: llama.cpp accepts a flag
+ * either way, so treating the two spellings as different would nag an operator
+ * whose plist merely writes them differently.
+ *
+ * Known limitation: a quoted VALUE that itself starts with a dash (`--alias
+ * "-Fast- Model"`) opens a group of its own, because a `ps` line has lost the
+ * quoting that would say otherwise. It costs only precision in the wording of a
+ * diff that is already being reported — the verdict is unaffected while nothing
+ * else changed, since both sides group the same way.
+ */
+function groupArgv(tokens: readonly string[]): { program: string; groups: string[] } {
+  const groups: string[] = [];
+  const leading: string[] = [];
+  let current: string[] | null = null;
+
+  const flush = (): void => {
+    if (current !== null) groups.push(current.join(" "));
+    current = null;
+  };
+
+  for (const token of tokens) {
+    if (token.startsWith("-") && token !== "-" && token !== "--") {
+      flush();
+      const equals = token.indexOf("=");
+      // Only a flag's own `=` is split; a VALUE may legitimately contain one
+      // (`--override-kv tokenizer.ggml.add_bos_token=bool:false`) and is left
+      // exactly as written.
+      current = equals > 0 ? [token.slice(0, equals), token.slice(equals + 1)] : [token];
+      continue;
+    }
+    if (current === null) leading.push(token);
+    else current.push(token);
+  }
+  flush();
+
+  return { program: leading.join(" "), groups };
+}
+
+/** The groups in `a` that `b` does not have, counting duplicates. */
+function missingFrom(a: readonly string[], b: readonly string[]): string[] {
+  const remaining = new Map<string, number>();
+  for (const group of b) remaining.set(group, (remaining.get(group) ?? 0) + 1);
+
+  const missing: string[] = [];
+  for (const group of a) {
+    const count = remaining.get(group) ?? 0;
+    if (count > 0) remaining.set(group, count - 1);
+    else missing.push(group);
+  }
+  return missing;
+}
+
+/** Whitespace-separated tokens, with the empties dropped. */
+function tokenize(line: string): string[] {
+  return line.split(/\s+/u).filter((token) => token !== "");
+}
+
+/**
+ * Diffs the live command line against the argv recorded at setup.
+ *
+ * `observed` is one `ps` line: the argv joined on single spaces, which is
+ * exactly what `recorded.join(" ")` produces — so an equal join is a clean
+ * verdict no matter how the argv was quoted, and quoting can never fake a drift.
+ *
+ * What counts as drift is deliberately narrow, because a false alarm on a
+ * correctly configured machine is as damaging as a missed one:
+ *   - ORDER is not drift. The groups are compared as multisets; a plist that
+ *     lists the same flags in a different order changed nothing about how the
+ *     server runs.
+ *   - A line the process list CUT SHORT is not drift. A truncated line is a
+ *     strict prefix of the recorded one that stops mid-token; that is reported
+ *     `unknown`. A line that stops exactly at a token boundary is NOT treated as
+ *     truncation — that is the single most likely real edit (deleting the last
+ *     flag), and swallowing it would defeat the whole check.
+ *   - Nothing recorded, nothing observed, or a `ps` PLACEHOLDER in place of a
+ *     command line is `unknown`, never `clean`.
+ */
+export function diffLaunchArgv(recorded: readonly string[], observed: string): LaunchDrift {
+  const expectedTokens = recorded.filter((token) => token !== "");
+  if (expectedTokens.length === 0) {
+    return unknownLaunchDrift("no launch command was recorded for this machine");
+  }
+
+  const line = observed.trim();
+  if (line === "" || PLACEHOLDER_COMMAND.test(line)) {
+    return unknownLaunchDrift("the process list reported no command line");
+  }
+
+  const expected = expectedTokens.join(" ");
+  if (line === expected) {
+    return { status: "clean", added: [], removed: [], program: null, reason: null };
+  }
+
+  // Cut mid-token: `ps` gave us less than the process actually holds, so there
+  // is no verdict to reach — saying "these flags were removed" here would
+  // invent drift out of a display width.
+  if (expected.startsWith(line) && expected.charAt(line.length) !== " ") {
+    return unknownLaunchDrift("the process list truncated the command line");
+  }
+
+  const before = groupArgv(expectedTokens);
+  const after = groupArgv(tokenize(line));
+  const added = missingFrom(after.groups, before.groups);
+  const removed = missingFrom(before.groups, after.groups);
+  const program = before.program === after.program ? null : after.program;
+
+  if (added.length === 0 && removed.length === 0 && program === null) {
+    // Same program, same groups: the two lines differ only in the order the
+    // flags were written, which changes nothing the server does.
+    return { status: "clean", added: [], removed: [], program: null, reason: null };
+  }
+
+  return {
+    status: "drifted",
+    added,
+    removed,
+    program: program === null ? null : { recorded: before.program, observed: program },
+    reason: null,
+  };
+}