@hybridlabor-api/aos 4.7.2 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.7.2",
+  "version": "4.9.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "engines": {
@@ -24,8 +24,10 @@
     "validate": "node scripts/validate-skills.mjs",
     "validate:strict": "node scripts/validate-skills.mjs --strict",
     "store:index": "node scripts/build-ecc-store-index.mjs",
+    "plugin:build": "node scripts/build-plugin-manifest.mjs",
+    "plugin:check": "node scripts/build-plugin-manifest.mjs --check",
     "doctor": "node bin/aos-doctor.mjs",
-    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs"
+    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -58,6 +60,8 @@
     "mcps/",
     "scripts/",
     "vendor/",
+    "packages/aos-cli/",
+    "!packages/aos-cli/node_modules",
     "!mcps/**/*.png",
     "!mcps/**/*.jpg",
     "!mcps/**/*.jpeg",

package/packages/aos-cli/README.md

@@ -0,0 +1,80 @@
+# AOS CLI
+
+The AOS dispatcher contract and AOS skills, on the [pi](https://github.com/earendil-works/pi) coding agent.
+
+```
+aos-cli
+aos-cli "why is the go build failing"
+aos-cli --continue
+```
+
+## Which skills are loaded
+
+**Ten, not all of them.** pi advertises every discovered skill by name and description in *every* system prompt. Measured on this machine: 210 skills, **~11,150 tokens per request**, of which the four `firecrawl` entries alone are ~2,250. That is a permanent tax on every turn.
+
+`core-skills.json` narrows that to the handful worth having always:
+
+```
+ask-tim  aos-setup  aos-project-init  mcp-manage  systematic-debugging
+planning-with-files  token-saver-config  archify  deja-memory  grill-me
+```
+
+Edit the file. It is a flat list of directory names under `~/.agents/skills/`, nothing more.
+
+**The tradeoff, stated plainly:** a skill outside that list is not merely unadvertised — it is unreachable, `/skill:name` included. That is the cost of `--no-skills`, and it is why `aos-store` is how one gets added. If you want a skill in every session, put it in the list.
+
+Names that are not installed are skipped with a note rather than being fatal: the list should quietly shrink when a skill is pruned, not stop pi from starting.
+
+## In-session commands
+
+| | |
+|---|---|
+| `/aos-status` | Runs `aos-doctor --json` and shows every check, with the failing ones marked |
+| `/aos` | Menu: status, or the command to run outside for install / update / uninstall |
+
+Both are **read-only**. `aos-doctor --json` exits 1 whenever a check is not ok, which is the normal "something needs attention" answer, so the exit code is ignored and the report's own `ok` field decides. The install, update and uninstall entries do not spawn the installer: it animates and prompts, and nesting it inside pi's TUI corrupts both renderers. They report the command to run in a separate terminal instead.
+
+## What it actually is
+
+A launcher, not a reimplementation. It adds three things to a plain `pi`:
+
+| | |
+|---|---|
+| **AOS theme** | `themes/aos.json` — pi's `dark`, with the AOS palette (purple, amethyst, gold, forge, emerald, beige) |
+| **Dispatcher graph** | `~/.agents/AGENTS.md` appended to the system prompt |
+| **AOS skills** | nothing to do — pi already discovers `~/.agents/skills` (Agent Skills spec) |
+
+Everything else — the agent loop, the model providers, the TUI, sessions, MCP-less tool use — is pi's. AOS CLI does not fork pi and does not wrap it; it starts it with three flags.
+
+## What it deliberately does not do
+
+**It does not depend on `@hybridlabor-api/aos`.** It reads `~/.agents/` at runtime, which the `aos` installer writes. That is the whole contract:
+
+- AOS CLI and the AOS installer version and update independently. A pi update never drags in a 98 MB AOS reinstall.
+- AOS CLI runs without AOS installed — it just starts with no AOS skills and says so.
+- **It is not a pipeline executor.** The 7-node dispatcher graph reaches pi as instructions in `~/.agents/AGENTS.md`, not as machinery: the nodes are agent definitions, and the main session acts as the dispatcher, which is what `.agents/graph.md` specifies anyway. There is no `state.json` loop.
+- **No MCP.** pi has no MCP client, so memB, deja and mcsc are not available here. AOS CLI is a chat + skills harness; the other seven harnesses remain the machinery.
+
+## Install
+
+Through the AOS installer (picks this up automatically once the menu entry lands), or directly:
+
+```sh
+npm i -g @earendil-works/pi-coding-agent   # if you do not have pi yet
+cd packages/aos-cli && npm i && npm link
+```
+
+Requires Node >= 22.19 — pi's floor. The AOS installer itself still supports Node >= 20, because AOS CLI is a separate install step.
+
+## Layout
+
+```
+bin/aos-cli.mjs          the launcher (~40 lines)
+themes/aos.json          pi dark theme, AOS palette
+extensions/aos.ts        /aos and /aos-status
+scripts/check-theme.mjs  theme contract guard, run by `npm test`
+```
+
+## Licence
+
+MIT, same as AOS. pi is MIT, © the pi authors.

package/packages/aos-cli/bin/aos-cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// AOS CLI -- the AOS dispatcher contract on top of the pi coding agent.
+//
+// What this is: a launcher. Everything it provides already exists --
+//   * the AOS skills live in ~/.agents/skills, which the `aos` installer
+//     writes and which pi discovers natively (Agent Skills spec);
+//   * the 7-node dispatcher graph lives in ~/.agents/AGENTS.md.
+//
+// What this is not: a second copy of the AOS payload. It reads ~/.agents at
+// runtime and never imports @hybridlabor-api/aos, so AOS CLI and the installer
+// version and update independently. That is why pi updates are cheap here and
+// AOS updates are cheap there.
+//
+//   aos-cli                      open the chat in the current directory
+//   aos-cli "fix the failing go build"   same, with a first prompt
+//   aos-cli --continue           resume the last session for this project
+//   any other flag is handed to pi unchanged
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const agents = path.join(os.homedir(), '.agents');
+
+const args = [
+    '--theme', path.join(root, 'themes', 'aos.json'),
+    '--use-theme', 'aos',
+    '--extension', path.join(root, 'extensions', 'aos.ts'),
+];
+
+// pi discovers AGENTS.md from the working directory and its ancestors only, and
+// ~/.agents/AGENTS.md is neither. Without this flag the dispatcher graph -- the
+// one thing a bare pi genuinely cannot see -- is silently missing.
+const dispatch = path.join(agents, 'AGENTS.md');
+if (existsSync(dispatch)) {
+    args.push('--append-system-prompt', dispatch);
+} else {
+    console.error('AOS CLI: ~/.agents not found -- run `npx @hybridlabor-api/aos` first.');
+    console.error('         Starting without the AOS skills and the dispatcher graph.');
+}
+
+// pi advertises every discovered skill by name and description in EVERY system
+// prompt. Measured on this machine: 210 skills, ~11.150 tokens per request, of
+// which the four firecrawl entries alone are ~2.250. That is a permanent tax on
+// every turn to make one skill discoverable.
+//
+// core-skills.json narrows it to the handful worth having always. pi does the
+// work natively: --no-skills stops the discovery walk, and each --skill is added
+// back explicitly. --skill alone would not do it -- it appends to discovery
+// rather than replacing it.
+//
+// The tradeoff is that a skill outside this list is not merely unadvertised but
+// unreachable, not even via /skill:name. `aos-store` is how one gets added.
+const core = coreSkills();
+if (core.length) {
+    args.push('--no-skills');
+    for (const name of core) args.push('--skill', path.join(agents, 'skills', name));
+}
+
+/**
+ * The core skill list, skipping names that are not installed.
+ *
+ * A missing entry is not fatal: the point of the list is to cut the prompt
+ * tax, and a skill that was pruned or renamed upstream should quietly reduce
+ * the set rather than stop pi from starting.
+ */
+function coreSkills() {
+    const file = path.join(root, 'core-skills.json');
+    let names;
+    try {
+        names = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (err) {
+        console.error(`AOS CLI: core-skills.json unreadable (${err.message}) -- loading all skills.`);
+        return [];
+    }
+    if (!Array.isArray(names)) {
+        console.error('AOS CLI: core-skills.json is not a list -- loading all skills.');
+        return [];
+    }
+    const found = names.filter((n) => typeof n === 'string' && existsSync(path.join(agents, 'skills', n)));
+    const absent = names.length - found.length;
+    if (absent) console.error(`AOS CLI: ${absent} core skill(s) not installed, skipped.`);
+    return found;
+}
+
+// Find pi's CLI entry by walking up to the package root that declares it.
+// Neither require.resolve nor a fixed depth works: pi's `exports` map exports
+// only its library entry, so `@earendil-works/pi-coding-agent/package.json`
+// and `/dist/bundle/cli.js` both throw ERR_PACKAGE_PATH_NOT_EXPORTED, and
+// npm leaves no node_modules/.bin/pi behind for a transitive dependency.
+// The resolved import specifier points inside the package, so from there the
+// root is at most a couple of levels up.
+function findPiEntry(startDir) {
+    let dir = startDir;
+    for (;;) {
+        const manifest = path.join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+                if (parsed.bin && parsed.bin.pi) return path.resolve(dir, parsed.bin.pi);
+            } catch {
+                // unreadable or malformed -- keep walking, a parent's manifest may still be pi's
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+function piInvocation() {
+    try {
+        const entry = findPiEntry(
+            path.dirname(fileURLToPath(import.meta.resolve('@earendil-works/pi-coding-agent')))
+        );
+        if (entry) return { command: process.execPath, prefix: [entry] };
+    } catch {
+        // pi is not installed next to us -- fall through to PATH
+    }
+    return { command: 'pi', prefix: [] };
+}
+
+const { command, prefix } = piInvocation();
+const child = spawn(command, [...prefix, ...args, ...process.argv.slice(2)], { stdio: 'inherit' });
+
+child.on('error', (err) => {
+    console.error(`AOS CLI: cannot start pi (${err.code ?? err.message}).`);
+    console.error('         Install it with: npm i -g @earendil-works/pi-coding-agent');
+    process.exit(1);
+});
+child.on('exit', (code, signal) => process.exit(signal ? 1 : code ?? 0));

package/packages/aos-cli/core-skills.json

@@ -0,0 +1,12 @@
+[
+	"ask-tim",
+	"aos-setup",
+	"aos-project-init",
+	"mcp-manage",
+	"systematic-debugging",
+	"planning-with-files",
+	"token-saver-config",
+	"archify",
+	"deja-memory",
+	"grill-me"
+]

package/packages/aos-cli/extensions/aos.ts

@@ -0,0 +1,321 @@
+/**
+ * AOS CLI commands -- `/aos` and `/aos-status`.
+ *
+ * Read-only by default. The AOS installer owns the terminal: it animates, it
+ * prompts, and pi's own docs say an extension must not create a second
+ * terminal renderer. So anything that needs a real TTY (install, update,
+ * uninstall) is reported as a command to run outside the session rather than
+ * spawned here -- a nested installer inside pi's TUI corrupts both.
+ *
+ * `aos-doctor --json` is the only thing this executes, and it is read-only.
+ * The shape it returns is stable and is asserted by tests/aos-doctor.test.mjs:
+ *   { ok, platform, arch, results: [{ area, name, ok, detail, warningOnly }] }
+ */
+
+import { spawn } from "node:child_process";
+import { connect } from "node:net";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+// DynamicBorder is re-exported by the agent package, not by pi-tui -- the
+// examples/extensions/preset.ts reference splits them the same way.
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+
+const DASHBOARD_PORT = 7900;
+const DOCTOR_TIMEOUT_MS = 20_000;
+const AUTH_TIMEOUT_MS = 8_000;
+
+/**
+ * Providers to check for credentials, in priority order.
+ *
+ * A second provider slots in here and nowhere else -- the check, the status
+ * row and the startup notice all read this list. pi owns provider auth, not the
+ * AOS installer: it already has a `/login` command, and the AOS installer has no
+ * business asking for an Anthropic key it will never use itself. AOS CLI only
+ * has to notice when nothing is configured and point at `/login`.
+ *
+ * Deliberately short. Reporting "no configured provider (checked: ...)" with an
+ * honest list beats claiming a global state this process cannot actually see.
+ */
+const PROVIDERS = ["anthropic", "google"] as const;
+
+interface DoctorResult {
+	area: string;
+	name: string;
+	ok: boolean;
+	detail: string;
+	warningOnly: boolean;
+}
+interface DoctorReport {
+	ok: boolean;
+	results: DoctorResult[];
+}
+
+/**
+ * Run aos-doctor and return its report whatever the exit code.
+ *
+ * aos-doctor exits 1 whenever any single check is not ok -- that is the normal
+ * "something needs attention" answer, not a failure to run. Rejecting on a
+ * non-zero exit threw away a valid 27-check report and rendered as
+ * "aos-doctor could not be run", which is the worst possible reading: it
+ * reports the absence of a check as if the check had passed. The report's own
+ * `ok` field is the verdict; the exit code carries no extra information.
+ */
+function runDoctor(): Promise<DoctorReport> {
+	return new Promise((resolve, reject) => {
+		// shell on Windows only: the global shims are .cmd there, and spawn
+		// does not resolve those without it.
+		const child = spawn("aos-doctor", ["--json"], {
+			timeout: DOCTOR_TIMEOUT_MS,
+			shell: process.platform === "win32",
+		});
+		let out = "";
+		let err = "";
+		child.stdout?.on("data", (c) => {
+			out += c;
+		});
+		child.stderr?.on("data", (c) => {
+			err += c;
+		});
+		child.once("error", reject);
+		child.once("close", (code) => {
+			try {
+				resolve(JSON.parse(out) as DoctorReport);
+			} catch {
+				reject(new Error(err.trim() || `aos-doctor produced no JSON (exit ${code})`));
+			}
+		});
+	});
+}
+
+/**
+ * Ask pi whether one provider has usable credentials.
+ *
+ * `pi auth check --provider <name> --json` is a documented CLI surface and
+ * exits 0 for every verdict, including not_ready, so the JSON is the answer and
+ * the exit code carries nothing. `pi --list-models` was the tempting shortcut
+ * and is wrong: it lists every provider pi knows about whether or not a key is
+ * present, so a model in the list says nothing about being able to use it.
+ *
+ * A provider this check cannot reach at all is "unknown", never "not ready" --
+ * those are different states and reporting one as the other is how a health
+ * check ends up lying.
+ */
+function checkProvider(provider: string): Promise<"ready" | "not_ready" | "unknown"> {
+	return new Promise((resolve) => {
+		// argv[1] is pi's own bundle, because pi is the process running this
+		// extension. PATH is the fallback for a launch that re-execs a bare `pi`.
+		const entry = process.argv[1];
+		const [command, prefix] =
+			entry && /pi/i.test(entry) ? [process.execPath, [entry]] : ["pi", []];
+
+		const child = spawn(command, [...prefix, "auth", "check", "--provider", provider, "--json"], {
+			timeout: AUTH_TIMEOUT_MS,
+			shell: process.platform === "win32",
+		});
+		let out = "";
+		child.stdout?.on("data", (c) => {
+			out += c;
+		});
+		child.once("error", () => resolve("unknown"));
+		child.once("close", () => {
+			try {
+				const parsed = JSON.parse(out) as { status?: string };
+				resolve(parsed.status === "ready" ? "ready" : "not_ready");
+			} catch {
+				resolve("unknown");
+			}
+		});
+	});
+}
+
+/** One row per provider, ready ones first, for the status overlay. */
+async function providerStatus(): Promise<{ provider: string; state: string }[]> {
+	return Promise.all(
+		PROVIDERS.map(async (provider) => ({ provider, state: await checkProvider(provider) })),
+	);
+}
+
+function portOpen(port: number, timeoutMs = 500): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = connect({ port, host: "127.0.0.1" });
+		const done = (up: boolean) => {
+			socket.destroy();
+			resolve(up);
+		};
+		socket.setTimeout(timeoutMs);
+		socket.once("connect", () => done(true));
+		socket.once("timeout", () => done(false));
+		socket.once("error", () => done(false));
+	});
+}
+
+async function showStatus(ctx: ExtensionContext): Promise<void> {
+	let report: DoctorReport | null = null;
+	let failure: string | null = null;
+	try {
+		report = await runDoctor();
+	} catch (err) {
+		failure = err instanceof Error ? err.message : String(err);
+	}
+	const dashboardUp = await portOpen(DASHBOARD_PORT);
+	const providers = await providerStatus();
+	const anyReady = providers.some((p) => p.state === "ready");
+
+	await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+
+		const mark = (ok: boolean) => theme.fg(ok ? "success" : "error", ok ? "●" : "○");
+
+		if (failure) {
+			container.addChild(new Text(theme.fg("error", "aos-doctor could not be run")));
+			container.addChild(new Text(theme.fg("muted", failure)));
+			container.addChild(new Text(theme.fg("dim", "It is installed by `npx @hybridlabor-api/aos`.")));
+		} else if (report) {
+			const failing = report.results.filter((r) => !r.ok);
+			container.addChild(
+				new Text(
+					theme.bold(
+						`AOS ${failing.length === 0 ? theme.fg("success", "healthy") : theme.fg("error", `${failing.length} failing check(s)`)}`,
+					),
+				),
+			);
+			container.addChild(new Text(""));
+			for (const r of report.results) {
+				container.addChild(new Text(`${mark(r.ok)} ${r.name}${r.ok ? "" : theme.fg("error", "  ← needs attention")}`));
+				if (r.detail) container.addChild(new Text(theme.fg("muted", `    ${r.detail}`)));
+			}
+		}
+
+		container.addChild(new Text(""));
+		container.addChild(
+			new Text(
+				`${mark(dashboardUp)} Dashboard :${DASHBOARD_PORT} ${
+					dashboardUp ? theme.fg("success", "running") : theme.fg("dim", "stopped -- run `npx aos-dashboard`")
+				}`,
+			),
+		);
+		container.addChild(
+			new Text(
+				`${mark(anyReady)} Model ${
+					anyReady
+						? theme.fg("success", providers.filter((p) => p.state === "ready").map((p) => p.provider).join(", "))
+						: theme.fg("error", "no provider configured -- run /login in pi")
+				}`,
+			),
+		);
+		container.addChild(new Text(""));
+		container.addChild(new Text(theme.fg("dim", "esc or enter to close")));
+		container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+
+		return {
+			render(width: number) {
+				return container.render(width);
+			},
+			invalidate() {
+				container.invalidate();
+			},
+			handleInput(data: string) {
+				if (data === "" || data === "\r" || data === "\n" || data === "") done();
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+export default function aosCommands(pi: ExtensionAPI) {
+	// Fire and forget on session_start: never block startup on it, and never
+	// repeat. A user without credentials can still read skills, run
+	// /aos-status and browse -- only sending a message needs a model, so this is
+	// a notice, not a gate.
+	//
+	// It says "at startup" on purpose. This handler runs once, so a /login
+	// completed inside the session leaves the warning standing next to a working
+	// model -- and a notice that is visible after you acted on it is worse than
+	// none, because it reads as a current fact. pi has no event this extension
+	// can rely on for "a login just landed", so rather than invent a poll or
+	// guess at an API, the wording states when it was true and /aos-status is
+	// the live reading. Measured: `pi auth check` returns ready/oauth once the
+	// browser flow completes, so that command and nothing else is the truth.
+	let warnedNoProvider = false;
+	pi.on("session_start", async (_event, ctx) => {
+		if (warnedNoProvider) return;
+		const providers = await providerStatus();
+		if (providers.some((p) => p.state === "ready")) return;
+		warnedNoProvider = true;
+		const unknown = providers.filter((p) => p.state === "unknown").map((p) => p.provider);
+		ctx.ui.notify(
+			`No model provider was configured at startup (checked: ${providers.map((p) => p.provider).join(", ")}). ` +
+				`Run /login to add one -- or /aos-status for the current state.`,
+			"warning",
+		);
+		if (unknown.length) {
+			ctx.ui.notify(`Could not reach pi's auth check for: ${unknown.join(", ")} -- treated as unverified, not as unconfigured.`, "info");
+		}
+	});
+
+	pi.registerCommand("aos-status", {
+		description: "AOS health, failing checks and daemon status",
+		handler: async (_args, ctx) => {
+			await showStatus(ctx);
+		},
+	});
+
+	pi.registerCommand("aos", {
+		description: "AOS menu: status, dashboard, or the command for a terminal action",
+		handler: async (_args, ctx) => {
+			const items: SelectItem[] = [
+				{ value: "status", label: "Status", description: "run aos-doctor and show failing checks" },
+				{ value: "update", label: "Skills & MCPs aktualisieren", description: "runs outside this session" },
+				{ value: "install", label: "AOS CLI nachinstallieren", description: "runs outside this session" },
+				{ value: "uninstall", label: "AOS deinstallieren", description: "runs outside this session" },
+			];
+
+			const choice = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+				const container = new Container();
+				container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+				container.addChild(new Text(theme.fg("accent", theme.bold("AOS"))));
+
+				const list = new SelectList(items, items.length, {
+					selectedPrefix: (t) => theme.fg("accent", t),
+					selectedText: (t) => theme.fg("accent", t),
+					description: (t) => theme.fg("muted", t),
+				});
+				list.onSelect = (item) => done(item.value);
+				list.onCancel = () => done(null);
+				container.addChild(list);
+
+				container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc cancel")));
+				container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+
+				return {
+					render(width: number) {
+						return container.render(width);
+					},
+					invalidate() {
+						container.invalidate();
+					},
+					handleInput(data: string) {
+						list.handleInput(data);
+						tui.requestRender();
+					},
+				};
+			});
+
+			if (choice === "status") {
+				await showStatus(ctx);
+				return;
+			}
+			if (!choice) return;
+
+			// The installer animates and prompts; running it with inherited stdio
+			// inside pi's TUI corrupts both renderers. Report the command instead.
+			const commands: Record<string, string> = {
+				update: "aos",
+				install: "aos",
+				uninstall: "npx @hybridlabor-api/aos-uninstall",
+			};
+			ctx.ui.notify(`Run this in a separate terminal:  ${commands[choice]}`, "info");
+		},
+	});
+}