noah-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sriman (NOAH contributors)
+
+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,169 @@
+# NOAH
+
+### An AI System Administrator for your terminal
+
+> Tell your machine what you want in plain English. NOAH **reads the machine**,
+> **analyzes the impact**, **recommends** the best action, and only then
+> **executes — with your approval, and a full audit trail.**
+
+NOAH is not another agent that blindly runs commands. It behaves like a senior
+sysadmin: it inspects real telemetry (disk, memory, processes, services, logs)
+*before* it acts, explains what will change, asks before anything dangerous, and
+**hard-blocks** the catastrophic. Cross-platform — Linux and macOS.
+
+```
+                ███╗   ██╗  ██████╗   █████╗  ██╗  ██╗
+                ████╗  ██║ ██╔═══██╗ ██╔══██╗ ██║  ██║
+                ██╔██╗ ██║ ██║   ██║ ███████║ ███████║
+                ██║╚██╗██║ ██║   ██║ ██╔══██║ ██╔══██║
+                ██║ ╚████║ ╚██████╔╝ ██║  ██║ ██║  ██║
+                ╚═╝  ╚═══╝  ╚═════╝  ╚═╝  ╚═╝ ╚═╝  ╚═╝
+           A G E N T I C   O P E R A T I N G   S Y S T E M
+
+ ◆ SYSTEM  macOS 14.5  ·  WARN
+   memory  ██████████████░░░░ 82%  (13.1 GB / 16.0 GB)
+   disk    █████████████████░ 86%  (70 GB free on /)
+ ◆ recommendations
+   ▸ Disk filling up       / at 86%
+   ▸ 3 updates available   Run a system update to stay current
+ ╭──────────────────────────────────────────────────────────╮
+ │ › how healthy is my machine?                             │
+ ╰──────────────────────────────────────────────────────────╯
+  ◆ claude-sonnet-4-5  ·  safety on        / commands · enter send
+```
+
+---
+
+## Why NOAH
+
+A coding copilot edits files in a repo. **NOAH operates the machine.** The
+difference is trust and awareness:
+
+| | Coding copilots | **NOAH** |
+|---|---|---|
+| Knows the machine | guesses | **reads live telemetry first** |
+| Destructive ops | runs them | **blocklist + confirm + dry-run** |
+| Accountability | none | **every action → `.noah/audit.jsonl`** |
+| Cross-platform | shells out, guesses apt/brew | **one tool, auto-routed per OS** |
+| Runs offline | rarely | **local Ollama, nothing leaves the box** |
+
+**Examples**
+- *"Install Docker"* → checks disk/memory/existing setup → recommends → installs → verifies.
+- *"Why is my laptop slow?"* → root-cause from real top processes + memory pressure, with severity.
+- *"Free up space"* → finds large files, stale caches → suggests **safe** cleanup → confirms.
+- *"How healthy is my machine?"* → full report with prioritized actions.
+
+---
+
+## Install
+
+```bash
+npm install -g noah-agent
+noah            # launch the interactive console
+```
+
+Authenticate once (Claude Pro/Max or an API key) from inside NOAH:
+
+```
+/login          # pick Anthropic · GitHub Copilot · ChatGPT/Codex
+```
+
+Or run a **local** model with [Ollama](https://ollama.com) (`ollama pull qwen2.5-coder`).
+
+---
+
+## Usage
+
+```bash
+noah                              # interactive AI-SysAdmin console (TUI)
+noah "install docker and verify"  # send a task on startup
+noah doctor                       # full machine health report (no LLM)
+noah --dry-run "free up space"    # preview; make no changes
+noah --print "show big files"     # single-shot, no TUI
+noah --rpc                        # headless JSON-RPC (embed NOAH)
+noah --list-models                # available models (✓ = ready)
+noah --check "rm -rf /"           # see how the safety gate classifies a command
+noah --log                        # print the audit trail
+```
+
+**In-console commands:** `/doctor` · `/model` · `/login` · `/logout` ·
+`/caveman` (token saver) · `/compact` · `/audit` · `/help` · `/clear` · `/quit`.
+
+---
+
+## Safety
+
+The gate lives in the **agent pipeline, not inside any tool** — nothing runs
+without passing through it.
+
+| Verdict | Examples | Behaviour |
+|---|---|---|
+| `deny` | `rm -rf /`, fork bomb, `mkfs`, `dd of=/dev/disk`, `shutdown` | Hard-blocked, no override |
+| `confirm` | installs, `sudo`, deletes, writes, service/network changes | Asks before running |
+| `allow` | `ls`, `grep`, telemetry reads, redirects to `/dev/null` | Runs freely |
+
+Dry-run neutralizes side effects. Every executed action is appended to
+`.noah/audit.jsonl`.
+
+---
+
+## Embed it (SDK)
+
+```ts
+import { createNoahSession } from "noah-agent/sdk";
+
+const { session } = await createNoahSession({ dryRun: false, autoYes: false });
+session.subscribe((e) => {
+  if (e.type === "message_update" && e.assistantMessageEvent.type === "text_delta")
+    process.stdout.write(e.assistantMessageEvent.delta);
+});
+await session.prompt("install htop and start it");
+session.dispose();
+```
+
+Also exported: `classify` (safety policy), `platform` (OS adapter),
+`collectSnapshot`/`assessHealth` (telemetry), `buildNoahRuntime` (for RPC).
+
+---
+
+## How it works
+
+```
+  Your request ── reads telemetry (system · logs) ── analyzes impact
+        │
+        ▼
+  SAFETY GATE        classify → deny / confirm / allow   + audit trail
+        │
+        ▼
+  TOOLS  bash · files · package · service · network · system · logs
+        │
+        ▼
+  PLATFORM ADAPTER   Linux (apt/dnf/pacman/zypper · systemd) · macOS (brew · launchd)
+        │
+        ▼
+      Host OS
+```
+
+Built on the [Pi](https://pi.dev) agent SDK (`@earendil-works/pi-coding-agent`)
+for the loop, sessions, streaming, and multi-provider transport; NOAH adds the
+OS tool layer, the telemetry/health engine, and the safety gate.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/srimanh/NOAH
+cd NOAH && npm install
+npm run build
+npm test          # full suite
+npm run dev -- "how healthy is my machine?"
+```
+
+Requires Node ≥ 20.6.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Sriman

package/dist/agent/auth-gate.js

@@ -0,0 +1,23 @@
+/**
+ * Auth gate — make /login and /logout actually mean something.
+ *
+ * After /logout the running session still holds a model, so without a gate the
+ * agent would keep answering. This checks the live credential before each prompt
+ * so signing out blocks usage until /login restores it (matching pi's behaviour).
+ */
+/** True if the provider currently has a stored credential (api key or oauth). */
+export function isAuthed(provider, store) {
+    return store.get(provider) != null;
+}
+/** Decide whether a prompt may run for the current model. */
+export function authGate(model, store) {
+    if (!model)
+        return { ok: false, reason: "No model selected. Use /model to choose one." };
+    if (!isAuthed(model.provider, store)) {
+        return {
+            ok: false,
+            reason: `Signed out of ${model.provider}. Run /login (subscription or API key) to reconnect.`,
+        };
+    }
+    return { ok: true };
+}

package/dist/agent/caveman.js

@@ -0,0 +1,44 @@
+export const CAVEMAN_LEVELS = ["lite", "full", "ultra", "micro"];
+export function isCavemanLevel(s) {
+    return s === "off" || CAVEMAN_LEVELS.includes(s);
+}
+const BASE = `IMPORTANT: You are in CAVEMAN MODE. Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Rules:
+- Drop articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries, hedging
+- Fragments OK. Short synonyms preferred. Technical terms exact
+- Code blocks unchanged. Errors quoted exact
+- Pattern: [thing] [action] [reason]. [next step].`;
+const SAFETY = `Auto-clarity: drop caveman for security warnings, irreversible action confirmations, or when the user is confused. Resume after.
+Boundaries: only compress explanations, never code. "stop caveman" or "normal mode" reverts.`;
+const INTENSITY = {
+    lite: `No filler/hedging. Keep articles + full sentences. Professional but tight.`,
+    full: `Drop articles, fragments OK, short synonyms.`,
+    ultra: `Abbreviate (DB/auth/config/req/res/fn/impl), strip conjunctions, arrows for causality (X → Y).`,
+};
+const MICRO = `# Token efficiency
+Respond like smart caveman. Cut all filler, keep technical substance.
+- Drop articles (a, an, the), filler (just, really, basically, actually).
+- Drop pleasantries. No hedging. Fragments fine. Short synonyms.
+- Technical terms exact. Code blocks unchanged.
+- Pattern: [thing] [action] [reason]. [next step].`;
+/** The system-prompt fragment for a level ("" when off). */
+export function cavemanInstruction(level) {
+    if (level === "off")
+        return "";
+    if (level === "micro")
+        return MICRO;
+    return `${BASE}\n\n${INTENSITY[level]}\n\n${SAFETY}`;
+}
+/**
+ * Extension that appends the caveman rules to each run's system prompt.
+ * `getLevel` is read at agent-start time so the level can be toggled live.
+ */
+export const cavemanExtension = (getLevel) => (pi) => {
+    pi.on("before_agent_start", (event) => {
+        const frag = cavemanInstruction(getLevel());
+        if (!frag)
+            return undefined;
+        return { systemPrompt: `${event.systemPrompt}\n\n${frag}` };
+    });
+};

package/dist/agent/login.js

@@ -0,0 +1,59 @@
+/**
+ * Login — reuses pi's real OAuth providers (Anthropic Claude Pro/Max,
+ * GitHub Copilot, ChatGPT/Codex) instead of reimplementing the flow.
+ *
+ * pi-ai hides the oauth module behind its exports map, so we resolve the
+ * installed package and import the file directly. The TUI supplies a LoginUI
+ * (browser-open, code paste, sub-select); we map it to pi's OAuthLoginCallbacks.
+ */
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/** Map our LoginUI to pi's OAuthLoginCallbacks shape. */
+export function buildCallbacks(ui) {
+    return {
+        onAuth: (info) => {
+            ui.note(`Opening your browser to sign in…\nIf it doesn't open, visit:\n${info.url}`);
+            ui.openUrl(info.url);
+        },
+        onDeviceCode: (info) => ui.note(`Go to ${info.verificationUri} and enter code:  ${info.userCode}`),
+        onProgress: (message) => ui.note(message),
+        onPrompt: (p) => ui.prompt(p.message),
+        onManualCodeInput: () => ui.prompt("Paste the authorization code:"),
+        onSelect: (p) => ui.select(p.message, p.options),
+    };
+}
+/** Tag raw OAuth credentials so AuthStorage persists them as a subscription. */
+export function oauthCredential(creds) {
+    return { type: "oauth", ...creds };
+}
+let oauthMod;
+function loadOAuth() {
+    if (!oauthMod) {
+        // pi-ai exposes oauth only as an internal (non-exported) module. Resolve the
+        // package's ESM entry, then walk to the oauth file by path and import it.
+        const idxPath = fileURLToPath(import.meta.resolve("@earendil-works/pi-ai"));
+        const file = join(dirname(idxPath), "utils", "oauth", "index.js");
+        oauthMod = import(pathToFileURL(file).href);
+    }
+    return oauthMod;
+}
+export async function listLoginProviders() {
+    const m = await loadOAuth();
+    return (m.getOAuthProviders?.() ?? []).map((p) => ({ id: p.id, name: p.name }));
+}
+/** Run pi's OAuth login for `id`, persist the credential, refresh models. */
+export async function runLogin(id, ui, authStorage, registry) {
+    try {
+        const m = await loadOAuth();
+        const provider = m.getOAuthProvider?.(id);
+        if (!provider)
+            return { ok: false, error: `unknown provider: ${id}` };
+        const creds = await provider.login(buildCallbacks(ui));
+        authStorage.set(id, oauthCredential(creds));
+        registry.refresh();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * NOAH CLI — `noah "<natural language task>"`
+ *
+ * Flags:
+ *   --dry-run   preview steps without executing (neutralises side effects)
+ *   --yes, -y   auto-approve confirmations (non-interactive demo / scripts)
+ *   --log       print the audit log and exit
+ *   --help, -h  usage
+ */
+import { runNoah } from "./session.js";
+import { runNoahInteractive } from "./tui/app.js";
+import { runNoahSpace } from "./tui/space/app.js";
+import { runNoahRpc } from "./modes/rpc.js";
+import { collectSnapshot } from "./sys/probe.js";
+import { assessHealth } from "./sys/health.js";
+import { formatDoctor } from "./sys/report.js";
+import { printAuditLog } from "./safety/audit.js";
+import { classify } from "./safety/policy.js";
+import { buildRegistry } from "./llm/registry.js";
+import { formatModelList } from "./llm/resolve.js";
+import * as ui from "./ui/render.js";
+const BANNER = "NOAH — Native Operating-system Agentic Harness";
+function usage() {
+    console.log(`${BANNER}
+
+Usage:
+  noah                                  Launch the interactive TUI
+  noah "install htop and start it"      TUI, sending your task first
+  noah --print "show my biggest files"  Single-shot, no TUI (scripts/demos)
+  noah --dry-run "set up a venv"         Preview steps; make no changes
+  noah doctor                           Full machine health report (no LLM)
+  noah --log                            Print the audit trail
+
+Flags:
+  --print          Single-shot branded run; do not open the TUI
+  --rpc            Headless JSON-RPC over stdin/stdout (embed NOAH)
+  --classic        Use the classic (pi-style) interactive mode
+  --caveman[=LVL]  Start in token-saver mode (off/lite/full/ultra/micro)
+  --dry-run        Preview the plan; do not execute (side effects neutralised)
+  --yes, -y        Auto-approve confirmation prompts
+  --model REF      Pick the LLM as provider/id (e.g. ollama/llama3.1)
+  --list-models    List available models (✓ = ready) and exit
+  --check CMD      Show how NOAH's safety gate would classify a shell command
+  --log            Print the audit trail and exit
+  --help, -h       Show this help
+`);
+}
+function checkCommand(command) {
+    const v = classify("bash", { command });
+    if (v.action === "deny") {
+        console.log(ui.safetyBlock(command, v.reason));
+        return;
+    }
+    console.log(ui.checkVerdict(command, v.action, v.reason));
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--help") || argv.includes("-h")) {
+        usage();
+        return;
+    }
+    if (argv.includes("--log")) {
+        printAuditLog();
+        return;
+    }
+    if (argv[0] === "doctor" || argv.includes("--doctor")) {
+        console.log(ui.brand());
+        const snap = await collectSnapshot();
+        console.log(formatDoctor(snap, assessHealth(snap)).join("\n"));
+        return;
+    }
+    if (argv.includes("--list-models")) {
+        const { modelRegistry } = await buildRegistry();
+        console.log(ui.brand());
+        console.log(formatModelList(modelRegistry));
+        return;
+    }
+    const checkIdx = argv.indexOf("--check");
+    if (checkIdx !== -1) {
+        const command = argv.slice(checkIdx + 1).join(" ").trim();
+        if (!command) {
+            console.error('✗ --check needs a command, e.g. noah --check "rm -rf /"');
+            process.exitCode = 1;
+            return;
+        }
+        console.log(ui.brand());
+        checkCommand(command);
+        return;
+    }
+    const dryRun = argv.includes("--dry-run");
+    const autoYes = argv.includes("--yes") || argv.includes("-y");
+    const printMode = argv.includes("--print");
+    const classicMode = argv.includes("--classic");
+    const rpcMode = argv.includes("--rpc") || argv.includes("--mode=rpc");
+    const modelIdx = argv.indexOf("--model");
+    const model = modelIdx !== -1 ? argv[modelIdx + 1] : undefined;
+    const caveArg = argv.find((a) => a === "--caveman" || a.startsWith("--caveman="));
+    const caveman = caveArg ? (caveArg.split("=")[1] ?? "full") : undefined;
+    const prompt = argv
+        .filter((a, i) => !a.startsWith("-") && i !== modelIdx + 1)
+        .join(" ")
+        .trim();
+    try {
+        if (rpcMode) {
+            await runNoahRpc({ dryRun, autoYes, model, caveman });
+        }
+        else if (printMode) {
+            if (!prompt) {
+                console.error("✗ --print needs a task.\n");
+                usage();
+                process.exitCode = 1;
+                return;
+            }
+            await runNoah({ prompt, dryRun, autoYes, model });
+        }
+        else if (classicMode) {
+            await runNoahInteractive({ initialMessage: prompt || undefined, dryRun, autoYes, model });
+        }
+        else {
+            // Default: NOAH's bespoke space TUI.
+            await runNoahSpace({ initialMessage: prompt || undefined, dryRun, autoYes, model, caveman });
+        }
+    }
+    catch (err) {
+        console.error(`\n✗ NOAH error: ${err.message}`);
+        process.exitCode = 1;
+    }
+}
+main();

package/dist/llm/ollama.js

@@ -0,0 +1,32 @@
+/**
+ * Ollama dynamic model discovery.
+ *
+ * Queries the local Ollama daemon for installed models so NOAH lists exactly
+ * what the user has pulled. Always degrades gracefully: if Ollama is down or the
+ * payload is odd, returns [] and the caller falls back to the static defaults.
+ */
+import { OLLAMA_BASE_URL, ollamaModelConfig } from "./providers.js";
+/** Derive Ollama's native `/api/tags` endpoint from the OpenAI-compat `/v1` base url. */
+export function tagsUrl(baseUrl) {
+    const root = baseUrl.replace(/\/v1\/?$/, "").replace(/\/$/, "");
+    return `${root}/api/tags`;
+}
+export async function discoverOllamaModels(opts = {}) {
+    const baseUrl = opts.baseUrl ?? OLLAMA_BASE_URL;
+    const doFetch = opts.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(tagsUrl(baseUrl));
+        if (!res.ok)
+            return [];
+        const body = (await res.json());
+        if (!Array.isArray(body.models))
+            return [];
+        return body.models
+            .map((t) => t.name)
+            .filter((n) => typeof n === "string" && n.length > 0)
+            .map((id) => ollamaModelConfig(id));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/llm/providers.js

@@ -0,0 +1,38 @@
+/** Default local Ollama OpenAI-compatible endpoint. */
+export const OLLAMA_BASE_URL = "http://localhost:11434/v1";
+/** Sensible local defaults (good tool-calling models). */
+export const DEFAULT_OLLAMA_MODELS = ["qwen2.5-coder", "llama3.1"];
+/**
+ * Build a model config for a local Ollama model.
+ * Local inference is free, text-only, no extended thinking by default.
+ */
+export function ollamaModelConfig(id, overrides = {}) {
+    return {
+        id,
+        name: id,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 32_768,
+        maxTokens: 4096,
+        ...overrides,
+    };
+}
+/**
+ * Build a ProviderConfig for local Ollama.
+ *
+ * A dummy apiKey is set so Pi treats these models as "available" (auth configured);
+ * Ollama ignores the bearer token for local use.
+ */
+export function ollamaProvider(opts = {}) {
+    const ids = opts.models ?? [...DEFAULT_OLLAMA_MODELS];
+    const models = ids.map((m) => (typeof m === "string" ? ollamaModelConfig(m) : m));
+    return {
+        name: "Ollama (local)",
+        baseUrl: opts.baseUrl ?? OLLAMA_BASE_URL,
+        apiKey: "ollama",
+        authHeader: true,
+        api: "openai-completions",
+        models,
+    };
+}

package/dist/llm/registry.js

@@ -0,0 +1,19 @@
+/**
+ * Registry assembly — wires Pi's AuthStorage + ModelRegistry and registers
+ * NOAH's pluggable providers (local Ollama first; cloud providers come from
+ * Pi's built-ins + ~/.pi auth).
+ */
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { discoverOllamaModels } from "./ollama.js";
+import { ollamaProvider, OLLAMA_BASE_URL } from "./providers.js";
+export async function buildRegistry(opts = {}) {
+    const baseUrl = opts.baseUrl ?? OLLAMA_BASE_URL;
+    const authStorage = opts.authStorage ?? AuthStorage.create();
+    const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
+    const discover = opts.discover ?? discoverOllamaModels;
+    const discovered = await discover({ baseUrl });
+    // Discovered models win; otherwise register the built-in defaults so the
+    // provider still appears (and works once the user pulls a model).
+    modelRegistry.registerProvider("ollama", ollamaProvider({ baseUrl, models: discovered.length ? discovered : undefined }));
+    return { authStorage, modelRegistry };
+}

package/dist/llm/resolve.js

@@ -0,0 +1,44 @@
+/** Parse "provider/id" (id may contain further slashes). Null if no provider segment. */
+export function parseModelRef(ref) {
+    const i = ref.indexOf("/");
+    if (i <= 0 || i === ref.length - 1)
+        return null;
+    return { provider: ref.slice(0, i), id: ref.slice(i + 1) };
+}
+export class ModelResolutionError extends Error {
+}
+function findRef(reg, ref) {
+    const parsed = parseModelRef(ref);
+    if (!parsed) {
+        throw new ModelResolutionError(`Invalid model ref "${ref}". Use provider/id, e.g. ollama/llama3.1`);
+    }
+    const found = reg.find(parsed.provider, parsed.id);
+    if (!found) {
+        throw new ModelResolutionError(`Model "${ref}" not found. Run \`noah --list-models\` to see options.`);
+    }
+    return found;
+}
+export function resolveModel(reg, opts) {
+    if (opts.flagModel)
+        return findRef(reg, opts.flagModel);
+    if (opts.envModel)
+        return findRef(reg, opts.envModel);
+    const available = reg.getAvailable();
+    if (available.length > 0)
+        return available[0];
+    throw new ModelResolutionError("No model available. Start Ollama (`ollama serve`) or configure a cloud key via `pi /login`, " +
+        "then pick one with `--model provider/id`.");
+}
+/** Human-readable model list for `--list-models`. ✓ marks models with auth configured. */
+export function formatModelList(reg) {
+    const available = new Set(reg.getAvailable().map((m) => `${m.provider}/${m.id}`));
+    const all = reg.getAll();
+    if (all.length === 0)
+        return "No models registered.";
+    const lines = all.map((m) => {
+        const ref = `${m.provider}/${m.id}`;
+        const mark = available.has(ref) ? "✓" : " ";
+        return `  ${mark} ${ref}`;
+    });
+    return ["Models (✓ = ready to use):", ...lines].join("\n");
+}

package/dist/modes/rpc.js

@@ -0,0 +1,13 @@
+/**
+ * RPC run mode — headless JSON-RPC over stdin/stdout, reusing pi's `runRpcMode`
+ * driven by a NOAH-wired runtime. Lets a desktop applet / voice frontend / any
+ * app embed NOAH as a subprocess with all OS tools + safety + caveman intact.
+ *
+ *   noah --rpc            # then send {"type":"prompt","message":"..."} lines
+ */
+import { runRpcMode } from "@earendil-works/pi-coding-agent";
+import { buildNoahRuntime } from "../runtime.js";
+export async function runNoahRpc(opts) {
+    const runtime = await buildNoahRuntime(opts);
+    await runRpcMode(runtime);
+}

package/dist/platform/adapter.js

@@ -0,0 +1,47 @@
+/**
+ * Platform adapter entry — detects the OS + package manager and wires the
+ * matching backend (Linux apt/dnf/pacman/zypper + systemd, or macOS brew + launchd).
+ *
+ * Detection logic lives in detect.ts (pure); this module supplies the real
+ * `has()` (PATH probe) and `sh()` (child process) seams.
+ */
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { detectPlatform } from "./detect.js";
+import { makeLinuxAdapter } from "./linux.js";
+import { makeMacosAdapter } from "./macos.js";
+const exec = promisify(execFile);
+/** Run a command, returning combined stdout+stderr; never throws (errors surface as text). */
+const sh = async (cmd, args) => {
+    try {
+        const { stdout, stderr } = await exec(cmd, args, { timeout: 120_000 });
+        return (stdout || "") + (stderr ? `\n${stderr}` : "");
+    }
+    catch (err) {
+        const e = err;
+        return e.stdout || e.stderr || e.message;
+    }
+};
+/** True if `cmd` is an executable on PATH (sync, no child process). */
+function hasOnPath(cmd) {
+    const dirs = (process.env.PATH ?? "").split(":").filter(Boolean);
+    for (const dir of dirs) {
+        try {
+            accessSync(join(dir, cmd), constants.X_OK);
+            return true;
+        }
+        catch {
+            // not here, keep looking
+        }
+    }
+    return false;
+}
+function build() {
+    const d = detectPlatform({ platform: process.platform, has: hasOnPath });
+    if (d.kind === "macos")
+        return makeMacosAdapter(sh);
+    return makeLinuxAdapter(d.pkgManager, sh);
+}
+export const platform = build();

package/dist/platform/detect.js

@@ -0,0 +1,18 @@
+/** Linux package managers probed in priority order: (binary, manager). */
+const LINUX_PMS = [
+    { bin: "apt-get", pm: "apt" },
+    { bin: "dnf", pm: "dnf" },
+    { bin: "pacman", pm: "pacman" },
+    { bin: "zypper", pm: "zypper" },
+];
+export function detectPlatform(input) {
+    if (input.platform === "darwin") {
+        return { kind: "macos", pkgManager: "brew" };
+    }
+    for (const { bin, pm } of LINUX_PMS) {
+        if (input.has(bin))
+            return { kind: "linux", pkgManager: pm };
+    }
+    // Unknown Linux: assume apt (most common); commands will surface real errors.
+    return { kind: "linux", pkgManager: "apt" };
+}