@pirol/nido 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# nido
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI für Agenten-Sandboxes, wie im Konzept
+[Agenten-Sandboxes auf OpenShell](../docs/concepts/agent-sandboxes.md)
+beschrieben. Man gibt nido einen Ordner, nido lässt darin einen Agenten
+arbeiten und holt die Ergebnisse zurück. Jede Sandbox läuft in einer eigenen
+Kata-VM.
+
+Stand: geschlossene Beta (#686–#688). nido spricht mit `pirol-agents-api`
+unter `https://nido.pirol.ai`. Die API prüft den Pirol-Schlüssel, trennt die
+Kunden und reicht die Aufrufe an das OpenShell-Gateway weiter. Die Doku für
+Kunden steht unter [pirol.ai/docs/sandboxes](https://pirol.ai/docs/sandboxes).
+
+## Einrichten
+
+Voraussetzung: Node 20 oder neuer und ein Pirol-Konto, das für die Beta
+freigeschaltet ist (`BETA_ALLOWLIST` in
+[deploy-agents-api.sh](../infra/agent-sandbox/deploy-agents-api.sh)).
+
+```bash
+npm install -g @pirol/nido
+nido login
+```
+
+`nido login` läuft wie `kyte login`: Der Browser öffnet pirol.ai, man
+bestätigt, und nido legt den Schlüssel in `~/.nido/config.json` ab (nur für
+den Nutzer lesbar). Ohne Browser hilft `nido login --manual`. In CI reicht
+die Umgebungsvariable `PIROL_API_KEY`. `NIDO_API_URL` zeigt nido auf eine
+andere API, etwa eine lokale.
+
+Aus dem Repo statt von npm:
+
+```bash
+cd nido && npm install && npm run build && npm link
+```
+
+## Ordner mit `nido.json`
+
+```bash
+mkdir survey && cd survey
+cp ~/Downloads/results.csv .
+nido init                       # writes nido.json for Claude Code
+nido secret set anthropic       # once, asks for the key without echo
+nido run
+```
+
+`nido.json`:
+
+```json
+{
+  "agent": "claude",
+  "task": "Analyze results.csv and write a report to output/report.md",
+  "files": { "exclude": ["node_modules", ".venv", "*.log"] },
+  "secrets": ["anthropic"],
+  "network": ["pypi.org", "files.pythonhosted.org"],
+  "output": "output/"
+}
+```
+
+Was `nido run` macht:
+
+1. Sandbox anlegen, falls es sie noch nicht gibt. Der Name kommt aus
+   `name` oder dem Ordnernamen. Ein neuer Start dauert etwa 20 Sekunden.
+2. Geänderte Dateien hochladen. nido merkt sich die Hashes in
+   `.nido/state.json`. Unveränderte Dateien gehen nicht noch einmal hoch,
+   lokal gelöschte verschwinden auch in der Sandbox.
+3. Den Agenten starten. Bei Claude zeigt nido jeden Schritt in einer Zeile.
+4. `output/` zurückholen. Neue Dateien landen im Ordner. Eine Datei, die
+   man lokal geändert hat, überschreibt nido nicht. Die Fassung aus der
+   Sandbox heißt dann zum Beispiel `report.remote.md`.
+
+Die Sandbox bleibt danach stehen. Der nächste `nido run` nutzt sie weiter,
+`nido run --fresh` fängt neu an.
+
+Statt eines Agenten geht auch ein Befehl, das braucht keinen Schlüssel:
+
+```json
+{ "command": "python analyze.py", "output": "output/" }
+```
+
+Felder:
+
+| Feld | Bedeutung |
+|---|---|
+| `agent` | `claude`, weitere folgen |
+| `task` | Auftrag an den Agenten |
+| `command` | statt `agent`: Befehl als Text (läuft in bash) oder Liste |
+| `name` | Name der Sandbox, sonst der Ordnername |
+| `image` | eigenes Image, sonst das OpenShell-Community-Image mit Claude Code, Codex und OpenCode |
+| `files.exclude` | Muster wie in `.gitignore`. `.git` und `.nido` bleiben immer draußen |
+| `secrets` | Namen von Secrets, nie die Werte |
+| `network` | Hosts, die die Sandbox auf Port 443 erreichen darf. Sonst ist das Netz zu |
+| `output` | Ordner, den nido zurückholt, Standard `output/` |
+
+## Secrets
+
+```bash
+nido secret set anthropic          # Anthropic API key
+nido secret set github --from-gh   # token from the GitHub CLI
+nido secret set openai
+nido secret ls
+nido secret rm github
+```
+
+Der Wert geht per HTTPS an die API und von dort über eine
+Umgebungsvariable an das Gateway, nie als Argument. Lesen kann ihn danach
+niemand mehr, auch der Kunde nicht.
+In der Sandbox steht nur ein Platzhalter. Der Proxy von OpenShell setzt den
+echten Wert erst beim Aufruf ein, und nur für die Hosts des Dienstes, etwa
+`api.anthropic.com`. Andere Namen kennt nido noch nicht.
+
+## Weitere Befehle
+
+```bash
+nido create shop --secret anthropic --network pypi.org
+nido ls
+nido exec shop -- ls -la /sandbox
+nido cp ./data shop:/sandbox/data
+nido cp shop:/sandbox/work/output ./out
+nido logs shop
+nido stop shop && nido start shop
+nido rm shop
+```
+
+## Entwicklung
+
+```bash
+npm test           # unit tests
+npm run build      # dist/
+```
+
+Die Regeln für Hoch- und Herunterladen stecken in `src/sync.ts` und sind
+reine Funktionen. Die Aufrufe an die API liegen in `src/api.ts`, die Anmeldung
+in `src/login.ts`. Mit OpenShell spricht nur noch
+[agents-api](../agents-api).
+
+Veröffentlichen: `npm publish` im Ordner `nido` (baut vorher neu).
+
+## Grenzen
+
+- Höchstens 5 Sandboxes pro Konto in der Beta.
+- `nido shell` fehlt noch. Stattdessen `nido exec`.
+- Der Agent läuft im Vordergrund. Bricht die Verbindung ab, holt
+  `nido pull` das, was schon in `output/` liegt.
+- Keine dauerhaften Arbeitsbereiche und kein Backup (#695).

package/dist/agents.js

@@ -0,0 +1,52 @@
+/** Working folder in the sandbox. The local folder ends up here. */
+export const WORKDIR = "/sandbox/work";
+/** The command that runs in the sandbox for a manifest. */
+export function agentCommand(m) {
+    if (m.agent === "claude") {
+        const task = `${m.task}\n\nPut every file meant for the user into ${m.output}/ (relative to the current folder).`;
+        return ["claude", "-p", task, "--dangerously-skip-permissions", "--output-format", "stream-json", "--verbose"];
+    }
+    if (typeof m.command === "string")
+        return ["bash", "-lc", m.command];
+    if (Array.isArray(m.command))
+        return m.command;
+    throw new Error("Nothing to run");
+}
+/**
+ * Claude Code's stream-json output, shortened to one line per step.
+ * Returns undefined for events that are not worth showing.
+ */
+export function formatClaudeEvent(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return line.trim() ? line : undefined;
+    }
+    if (event.type === "assistant") {
+        const parts = [];
+        for (const item of event.message?.content ?? []) {
+            if (item.type === "text" && item.text?.trim())
+                parts.push(item.text.trim());
+            if (item.type === "tool_use")
+                parts.push(`▸ ${item.name} ${summarizeInput(item.input)}`.trimEnd());
+        }
+        return parts.length ? parts.join("\n") : undefined;
+    }
+    if (event.type === "result") {
+        const seconds = event.duration_ms ? `${Math.round(event.duration_ms / 1000)} s` : "";
+        const cost = typeof event.total_cost_usd === "number" ? `$${event.total_cost_usd.toFixed(2)}` : "";
+        const status = event.is_error ? "failed" : "done";
+        return `■ ${status}${seconds || cost ? ` (${[seconds, cost].filter(Boolean).join(", ")})` : ""}`;
+    }
+    return undefined;
+}
+function summarizeInput(input) {
+    if (!input)
+        return "";
+    const value = input.command ?? input.file_path ?? input.path ?? input.pattern ?? input.url ?? input.description;
+    const text = typeof value === "string" ? value : "";
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length > 100 ? `${oneLine.slice(0, 97)}…` : oneLine;
+}

package/dist/api.js

@@ -0,0 +1,155 @@
+// Client for pirol-agents-api. Files travel as tar.gz streams, command
+// output comes back as NDJSON while the command runs.
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import { loadConfig } from "./config.js";
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class Api {
+    base;
+    key;
+    constructor(base, key) {
+        this.base = base;
+        this.key = key;
+    }
+    static fromConfig() {
+        const config = loadConfig();
+        if (!config.key)
+            throw new Error("Not logged in. Run: nido login");
+        return new Api(config.api, config.key);
+    }
+    async call(method, path, init = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.base}${path}`, {
+                ...init,
+                method,
+                headers: { authorization: `Bearer ${this.key}`, ...(init.headers ?? {}) },
+            });
+        }
+        catch (err) {
+            throw new Error(`Cannot reach ${this.base}: ${err.message}`);
+        }
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new ApiError(res.status, body.error ?? `HTTP ${res.status}`);
+        }
+        return res;
+    }
+    async json(method, path, body) {
+        const res = await this.call(method, path, {
+            headers: body === undefined ? {} : { "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        return (res.status === 204 ? undefined : await res.json());
+    }
+    whoami() {
+        return this.json("GET", "/v1/whoami");
+    }
+    async list() {
+        return (await this.json("GET", "/v1/sandboxes")).sandboxes;
+    }
+    async get(name) {
+        try {
+            return await this.json("GET", `/v1/sandboxes/${encodeURIComponent(name)}`);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return undefined;
+            throw err;
+        }
+    }
+    create(spec) {
+        return this.json("POST", "/v1/sandboxes", spec);
+    }
+    remove(name) {
+        return this.json("DELETE", `/v1/sandboxes/${encodeURIComponent(name)}`);
+    }
+    stop(name) {
+        return this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/stop`);
+    }
+    start(name) {
+        return this.json("POST", `/v1/sandboxes/${encodeURIComponent(name)}/start`);
+    }
+    async logs(name, lines = 200) {
+        return (await this.call("GET", `/v1/sandboxes/${encodeURIComponent(name)}/logs?lines=${lines}`)).text();
+    }
+    /** Runs a command; onOut/onErr get output as it arrives. Returns the exit code. */
+    async exec(name, command, opts) {
+        const res = await this.call("POST", `/v1/sandboxes/${encodeURIComponent(name)}/exec`, {
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ command, workdir: opts.workdir, stdin: opts.stdin }),
+        });
+        let exit = 1;
+        let partial = "";
+        const decoder = new TextDecoder();
+        for await (const chunk of res.body) {
+            const lines = (partial + decoder.decode(chunk, { stream: true })).split("\n");
+            partial = lines.pop() ?? "";
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                const event = JSON.parse(line);
+                if (event.o !== undefined)
+                    opts.onOut(event.o);
+                if (event.e !== undefined)
+                    opts.onErr(event.e);
+                if (event.exit !== undefined)
+                    exit = event.exit;
+            }
+        }
+        return exit;
+    }
+    /** Uploads the contents of a local folder into `path` (merging). */
+    async upload(name, localDir, path) {
+        // COPYFILE_DISABLE: macOS tar would add a ._ file with metadata for every file.
+        const tar = spawn("tar", ["-czf", "-", "-C", localDir, "."], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, COPYFILE_DISABLE: "1" },
+        });
+        let stderr = "";
+        tar.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+        const done = new Promise((resolve, reject) => tar.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`tar failed: ${stderr.trim()}`)))));
+        await this.call("PUT", `/v1/sandboxes/${encodeURIComponent(name)}/files?path=${encodeURIComponent(path)}`, {
+            headers: { "content-type": "application/gzip" },
+            body: Readable.toWeb(tar.stdout),
+            // @ts-expect-error Node's fetch needs this for streamed request bodies.
+            duplex: "half",
+        });
+        await done;
+    }
+    /** Downloads `path` into a local folder. Returns false if it does not exist. */
+    async download(name, path, localDir) {
+        let res;
+        try {
+            res = await this.call("GET", `/v1/sandboxes/${encodeURIComponent(name)}/files?path=${encodeURIComponent(path)}`);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return false;
+            throw err;
+        }
+        await new Promise((resolve, reject) => {
+            const tar = spawn("tar", ["-xzf", "-", "-C", localDir], { stdio: ["pipe", "ignore", "pipe"] });
+            let stderr = "";
+            tar.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+            tar.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`tar failed: ${stderr.trim()}`))));
+            Readable.fromWeb(res.body).pipe(tar.stdin);
+        });
+        return true;
+    }
+    async secrets() {
+        return (await this.json("GET", "/v1/secrets")).secrets;
+    }
+    async setSecret(name, value) {
+        return (await this.json("PUT", `/v1/secrets/${encodeURIComponent(name)}`, { value })).result;
+    }
+    removeSecret(name) {
+        return this.json("DELETE", `/v1/secrets/${encodeURIComponent(name)}`);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { copy, createSandbox, exec, init, list, login, logout, pull, runFolder, secretList, secretRemove, secretSet, simple, whoami, } from "./commands.js";
+const HELP = `nido — run agents in isolated sandboxes (closed beta)
+
+Start
+  nido login [--manual]        log in with your Pirol account
+  nido whoami | nido logout
+
+Folder workflow
+  nido init [--command]        write a nido.json into this folder
+  nido run [--fresh]           upload the folder, run the agent, bring output/ back
+  nido pull                    bring output/ back again
+
+Sandboxes
+  nido create <name> [--image <ref>] [--secret <name>]… [--network <host>]…
+  nido ls                      list your sandboxes
+  nido exec <name> -- <cmd>…   run a command
+  nido cp <src> <dst>          copy files; write the sandbox side as <name>:<path>
+  nido logs <name>             sandbox logs
+  nido stop|start|rm <name>
+
+Secrets (stored once, never readable again)
+  nido secret set <name> [--from-gh]   anthropic, openai, github
+  nido secret ls
+  nido secret rm <name>
+
+Docs: https://pirol.ai/docs/sandboxes
+`;
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    const { flags, args, passthrough } = parse(rest);
+    const one = (what) => {
+        if (!args[0])
+            throw new Error(`Usage: nido ${cmd} <${what}>`);
+        return args[0];
+    };
+    switch (cmd) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            process.stdout.write(HELP);
+            return 0;
+        case "version":
+        case "--version":
+            process.stdout.write(`nido ${version()}\n`);
+            return 0;
+        case "login":
+            await login({ manual: flags.has("manual") });
+            return 0;
+        case "whoami":
+            await whoami();
+            return 0;
+        case "logout":
+            logout();
+            return 0;
+        case "init":
+            init(process.cwd(), flags.has("command") ? "command" : "claude");
+            return 0;
+        case "run":
+            return runFolder(process.cwd(), { fresh: flags.has("fresh") });
+        case "pull":
+            await pull(process.cwd());
+            return 0;
+        case "create":
+            await createSandbox(one("name"), {
+                image: flags.get("image")?.[0],
+                secrets: flags.get("secret") ?? [],
+                network: flags.get("network") ?? [],
+            });
+            return 0;
+        case "ls":
+            await list();
+            return 0;
+        case "exec":
+            if (!passthrough.length)
+                throw new Error("Usage: nido exec <name> -- <command>…");
+            return exec(one("name"), passthrough);
+        case "shell":
+            throw new Error(`nido shell is not in the beta yet. Use: nido exec ${args[0] ?? "<name>"} -- <command>`);
+        case "logs":
+        case "stop":
+        case "start":
+        case "rm":
+            await simple(cmd, one("name"));
+            return 0;
+        case "cp":
+            if (args.length !== 2)
+                throw new Error("Usage: nido cp <src> <dst>  (sandbox side as <name>:<path>)");
+            await copy(args[0], args[1]);
+            return 0;
+        case "secret":
+            return secret(args, flags);
+        default:
+            throw new Error(`Unknown command "${cmd}". See: nido help`);
+    }
+}
+async function secret(args, flags) {
+    const [sub, name] = args;
+    if (sub === "set" && name)
+        await secretSet(name, { fromGh: flags.has("from-gh") });
+    else if (sub === "ls")
+        await secretList();
+    else if (sub === "rm" && name)
+        await secretRemove(name);
+    else
+        throw new Error("Usage: nido secret set <name> | nido secret ls | nido secret rm <name>");
+    return 0;
+}
+const VALUE_FLAGS = new Set(["image", "secret", "network"]);
+export function parse(argv) {
+    const flags = new Map();
+    const args = [];
+    const dash = argv.indexOf("--");
+    const own = dash === -1 ? argv : argv.slice(0, dash);
+    for (let i = 0; i < own.length; i++) {
+        const token = own[i];
+        if (!token.startsWith("--")) {
+            args.push(token);
+            continue;
+        }
+        const [key, inline] = token.slice(2).split(/=(.*)/s, 2);
+        const values = flags.get(key) ?? [];
+        if (VALUE_FLAGS.has(key)) {
+            const value = inline ?? own[++i];
+            if (value === undefined)
+                throw new Error(`--${key} needs a value`);
+            values.push(value);
+        }
+        flags.set(key, values);
+    }
+    return { flags, args, passthrough: dash === -1 ? [] : argv.slice(dash + 1) };
+}
+function version() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}
+// Run only as the program itself, not when tests import this file. npm
+// links the binary, so compare real paths.
+const isMain = (() => {
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMain) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`nido: ${err.message}\n`);
+        process.exit(1);
+    });
+}

package/dist/commands.js

@@ -0,0 +1,317 @@
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { agentCommand, formatClaudeEvent, WORKDIR } from "./agents.js";
+import { Api, ApiError } from "./api.js";
+import { forgetLogin, loadConfig, saveLogin } from "./config.js";
+import { excludeMatcher, hashFiles, listFiles } from "./files.js";
+import { loginWithPirol } from "./login.js";
+import { MANIFEST, manifestTemplate, readManifest } from "./manifest.js";
+import { secretKind } from "./secrets.js";
+import { planDownload, planUpload, readState, writeState } from "./sync.js";
+const say = (text) => void process.stderr.write(text + "\n");
+// ---------------------------------------------------------------- login
+export async function login(opts) {
+    const result = await loginWithPirol({ manual: opts.manual, ask });
+    saveLogin(result.key, result.email);
+    try {
+        const me = await Api.fromConfig().whoami();
+        say(`Logged in as ${me.email}`);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 403) {
+            say(`Logged in as ${result.email}. ${err.message}`);
+            return;
+        }
+        throw err;
+    }
+}
+export async function whoami() {
+    const config = loadConfig();
+    if (!config.key)
+        throw new Error("Not logged in. Run: nido login");
+    const me = await Api.fromConfig().whoami();
+    process.stdout.write(`${me.email}\n`);
+}
+export function logout() {
+    forgetLogin();
+    say("Logged out");
+}
+// ---------------------------------------------------------------- init
+export function init(dir, kind) {
+    const file = join(dir, MANIFEST);
+    if (existsSync(file))
+        throw new Error(`${MANIFEST} exists already`);
+    writeFileSync(file, manifestTemplate(kind));
+    say(`Wrote ${MANIFEST}. Edit the task, then: nido run`);
+    if (kind === "claude")
+        say("Claude needs your Anthropic key once: nido secret set anthropic");
+}
+// ---------------------------------------------------------------- sandboxes
+export async function createSandbox(name, spec) {
+    const api = Api.fromConfig();
+    say(`Creating sandbox ${name}…`);
+    const info = await api.create({ name, ...spec });
+    say(`Sandbox ${name} ready in ${(info.ready_ms / 1000).toFixed(1)} s`);
+}
+export async function list() {
+    const sandboxes = await Api.fromConfig().list();
+    if (!sandboxes.length)
+        return say("No sandboxes. Create one with: nido run or nido create <name>");
+    const width = Math.max(4, ...sandboxes.map((s) => s.name.length));
+    process.stdout.write(`${"NAME".padEnd(width)}  ${"CREATED".padEnd(19)}  PHASE\n`);
+    for (const s of sandboxes)
+        process.stdout.write(`${s.name.padEnd(width)}  ${s.created.padEnd(19)}  ${s.phase}\n`);
+}
+export async function exec(name, command) {
+    return Api.fromConfig().exec(name, command, {
+        onOut: (text) => process.stdout.write(text),
+        onErr: (text) => process.stderr.write(text),
+    });
+}
+export async function simple(action, name) {
+    const api = Api.fromConfig();
+    if (action === "rm")
+        await api.remove(name);
+    if (action === "stop")
+        await api.stop(name);
+    if (action === "start")
+        await api.start(name);
+    if (action === "logs")
+        return void process.stdout.write(await api.logs(name));
+    say(`${action === "rm" ? "Removed" : action === "stop" ? "Stopped" : "Started"} ${name}`);
+}
+/** nido cp: "shop:/sandbox/x" is in the sandbox, anything else is local. */
+export async function copy(src, dst) {
+    const remote = /^([a-z0-9][a-z0-9-]*):(\/.*)$/;
+    const from = remote.exec(src);
+    const to = remote.exec(dst);
+    const api = Api.fromConfig();
+    if (to && !from) {
+        const local = resolve(src);
+        if (!existsSync(local))
+            throw new Error(`${src} does not exist`);
+        if (statSync(local).isDirectory())
+            return api.upload(to[1], local, to[2]);
+        const tmp = mkdtempSync(join(tmpdir(), "nido-"));
+        try {
+            copyFileSync(local, join(tmp, basename(local)));
+            await api.upload(to[1], tmp, to[2]);
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        return;
+    }
+    if (from && !to) {
+        mkdirSync(resolve(dst), { recursive: true });
+        if (!(await api.download(from[1], from[2], resolve(dst))))
+            throw new Error(`${from[2]} does not exist in ${from[1]}`);
+        return;
+    }
+    throw new Error("nido cp copies between this machine and one sandbox: nido cp ./data shop:/sandbox/data");
+}
+// ---------------------------------------------------------------- run
+/** nido run: upload the folder, run the agent, bring the results back. */
+export async function runFolder(dir, opts = {}) {
+    const m = readManifest(dir);
+    const api = Api.fromConfig();
+    const isNew = await ensureSandbox(api, m, Boolean(opts.fresh));
+    const state = readState(dir, m.name);
+    if (isNew)
+        state.uploaded = {};
+    await upload(api, dir, m, state.uploaded);
+    writeState(dir, state);
+    const command = agentCommand(m);
+    say(m.agent ? `Running ${m.agent} in ${m.name}…` : `Running in ${m.name}: ${command.join(" ")}`);
+    let partial = "";
+    const code = await api.exec(m.name, command, {
+        workdir: WORKDIR,
+        onOut: m.agent
+            ? (text) => {
+                const lines = (partial + text).split("\n");
+                partial = lines.pop() ?? "";
+                for (const line of lines) {
+                    const shown = formatClaudeEvent(line);
+                    if (shown)
+                        process.stdout.write(shown + "\n");
+                }
+            }
+            : (text) => process.stdout.write(text),
+        onErr: (text) => process.stderr.write(text),
+    });
+    await download(api, dir, m, state.downloaded);
+    writeState(dir, state);
+    say(`Sandbox ${m.name} keeps running. Remove it with: nido rm ${m.name}`);
+    return code;
+}
+/** nido pull: fetch the output folder again. */
+export async function pull(dir) {
+    const m = readManifest(dir);
+    const api = Api.fromConfig();
+    if (!(await api.get(m.name)))
+        throw new Error(`Sandbox ${m.name} does not exist`);
+    const state = readState(dir, m.name);
+    await download(api, dir, m, state.downloaded);
+    writeState(dir, state);
+}
+async function ensureSandbox(api, m, fresh) {
+    let info = await api.get(m.name);
+    if (info && fresh) {
+        await api.remove(m.name);
+        info = undefined;
+    }
+    if (!info) {
+        say(`Creating sandbox ${m.name}…`);
+        const created = await api.create({ name: m.name, image: m.imageSet ? m.image : undefined, secrets: m.secrets, network: m.network });
+        say(`Sandbox ${m.name} ready in ${(created.ready_ms / 1000).toFixed(1)} s`);
+        return true;
+    }
+    if (info.phase !== "Ready")
+        await api.start(m.name);
+    return false;
+}
+async function upload(api, dir, m, uploaded) {
+    const isExcluded = excludeMatcher([...m.exclude, `/${m.output}`]);
+    const local = await hashFiles(dir, listFiles(dir, isExcluded));
+    const plan = planUpload(local, uploaded);
+    if (!plan.changed.length && !plan.removed.length)
+        return say("Files unchanged, nothing to upload");
+    if (plan.changed.length) {
+        const stage = mkdtempSync(join(tmpdir(), "nido-"));
+        try {
+            for (const path of plan.changed) {
+                mkdirSync(dirname(join(stage, path)), { recursive: true });
+                copyFileSync(join(dir, path), join(stage, path));
+            }
+            say(`Uploading ${count(plan.changed.length, "file")}…`);
+            await api.upload(m.name, stage, WORKDIR);
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+        }
+    }
+    if (plan.removed.length) {
+        await api.exec(m.name, ["rm", "-f", "--", ...plan.removed], { workdir: WORKDIR, onOut: () => { }, onErr: () => { } });
+    }
+    for (const path of plan.removed)
+        delete uploaded[path];
+    Object.assign(uploaded, local);
+}
+async function download(api, dir, m, downloaded) {
+    const tmp = mkdtempSync(join(tmpdir(), "nido-"));
+    try {
+        if (!(await api.download(m.name, `${WORKDIR}/${m.output}`, tmp))) {
+            return say(`No ${m.output}/ in the sandbox, nothing to bring back`);
+        }
+        const paths = listFiles(tmp, () => false);
+        const remote = await hashFiles(tmp, paths);
+        const outDir = join(dir, m.output);
+        const local = await hashFiles(outDir, paths.filter((path) => existsSync(join(outDir, path))));
+        const lines = [];
+        for (const action of planDownload(remote, local, downloaded)) {
+            const target = action.kind === "conflict" ? action.savedAs : action.path;
+            if (action.kind !== "same") {
+                mkdirSync(dirname(join(outDir, target)), { recursive: true });
+                copyFileSync(join(tmp, action.path), join(outDir, target));
+            }
+            // A conflict leaves the user's file alone; its last download stays
+            // the reference, so the next pull reports it again.
+            if (action.kind !== "conflict")
+                downloaded[action.path] = remote[action.path];
+            if (action.kind === "new")
+                lines.push(`  + ${m.output}/${action.path}`);
+            if (action.kind === "update")
+                lines.push(`  ~ ${m.output}/${action.path}`);
+            if (action.kind === "conflict") {
+                lines.push(`  ! ${m.output}/${action.path} changed here too, sandbox version saved as ${m.output}/${action.savedAs}`);
+            }
+        }
+        say(lines.length ? `Results:\n${lines.join("\n")}` : "Results unchanged");
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+function count(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+// ---------------------------------------------------------------- secrets
+export async function secretSet(name, opts) {
+    const kind = secretKind(name);
+    let value;
+    if (opts.fromGh) {
+        const { run } = await import("./run.js");
+        const gh = await run("gh", ["auth", "token"]);
+        if (gh.code !== 0)
+            throw new Error("gh auth token failed. Log in with: gh auth login");
+        value = gh.stdout.trim();
+    }
+    else {
+        value = (await readSecret(`${kind.hint}: `)).trim();
+    }
+    if (!value)
+        throw new Error("No value given");
+    const result = await Api.fromConfig().setSecret(name, value);
+    say(result === "updated" ? `Updated secret ${name}. Running sandboxes get it for new processes.` : `Saved secret ${name}`);
+}
+export async function secretList() {
+    const names = await Api.fromConfig().secrets();
+    process.stdout.write(names.length ? names.join("\n") + "\n" : "");
+    if (!names.length)
+        say("No secrets yet. Add one with: nido secret set anthropic");
+}
+export async function secretRemove(name) {
+    await Api.fromConfig().removeSecret(name);
+    say(`Removed secret ${name}`);
+}
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Reads a value without echo; from stdin when it is not a terminal. */
+async function readSecret(prompt) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        let data = "";
+        for await (const chunk of stdin)
+            data += chunk;
+        return data;
+    }
+    process.stderr.write(prompt);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    return new Promise((resolvePromise, reject) => {
+        let value = "";
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === "\r" || char === "\n")
+                    return done();
+                if (char === "\u0003")
+                    return done(new Error("Cancelled"));
+                if (char === "\u007f")
+                    value = value.slice(0, -1);
+                else
+                    value += char;
+            }
+        };
+        const done = (err) => {
+            stdin.off("data", onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+            process.stderr.write("\n");
+            if (err)
+                reject(err);
+            else
+                resolvePromise(value);
+        };
+        stdin.on("data", onData);
+    });
+}

package/dist/config.js

@@ -0,0 +1,35 @@
+// Where nido finds the API and the Pirol key. `nido login` writes
+// ~/.nido/config.json (0600); PIROL_API_KEY and NIDO_API_URL override it,
+// for CI and for agents that already hold a key.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { nidoHome } from "./paths.js";
+export const DEFAULT_API = "https://nido.pirol.ai";
+function file() {
+    return join(nidoHome(), "config.json");
+}
+export function loadConfig() {
+    let saved = {};
+    if (existsSync(file())) {
+        try {
+            saved = JSON.parse(readFileSync(file(), "utf8"));
+        }
+        catch {
+            saved = {};
+        }
+    }
+    return {
+        api: (process.env.NIDO_API_URL ?? saved.api ?? DEFAULT_API).replace(/\/+$/, ""),
+        key: process.env.PIROL_API_KEY ?? saved.key,
+        email: process.env.PIROL_API_KEY ? undefined : saved.email,
+    };
+}
+export function saveLogin(key, email, api) {
+    mkdirSync(nidoHome(), { recursive: true, mode: 0o700 });
+    const current = existsSync(file()) ? JSON.parse(readFileSync(file(), "utf8")) : {};
+    writeFileSync(file(), JSON.stringify({ ...current, ...(api ? { api } : {}), key, email }, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(file(), 0o600);
+}
+export function forgetLogin() {
+    rmSync(file(), { force: true });
+}

package/dist/files.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { createReadStream, readdirSync } from "node:fs";
+import { join, posix } from "node:path";
+/** Never uploaded: nido's own state and version control. */
+const ALWAYS_EXCLUDED = [".nido", ".git", ".DS_Store"];
+/**
+ * Turns an exclude pattern into a test on relative paths (with "/").
+ * Without a slash a pattern matches any file or folder name, like
+ * .gitignore. With a slash it matches the path from the folder root.
+ */
+export function excludeMatcher(patterns) {
+    const tests = [...ALWAYS_EXCLUDED, ...patterns].map((raw) => {
+        const pattern = raw.replace(/\/+$/, "");
+        const anchored = pattern.includes("/");
+        const regex = globToRegex(pattern.replace(/^\//, ""));
+        return anchored
+            ? (path) => prefixes(path).some((p) => regex.test(p))
+            : (path) => path.split("/").some((segment) => regex.test(segment));
+    });
+    return (path) => tests.some((test) => test(path));
+}
+function prefixes(path) {
+    const parts = path.split("/");
+    return parts.map((_, i) => parts.slice(0, i + 1).join("/"));
+}
+export function globToRegex(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*" && glob[i + 1] === "*") {
+            out += ".*";
+            i++;
+            if (glob[i + 1] === "/")
+                i++;
+        }
+        else if (c === "*")
+            out += "[^/]*";
+        else if (c === "?")
+            out += "[^/]";
+        else
+            out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+/** All regular files under root, as sorted paths relative to root. */
+export function listFiles(root, isExcluded) {
+    const out = [];
+    const walk = (rel) => {
+        for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) {
+            const path = rel ? posix.join(rel, entry.name) : entry.name;
+            if (isExcluded(path))
+                continue;
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile())
+                out.push(path);
+        }
+    };
+    walk("");
+    return out.sort();
+}
+export function hashFile(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        createReadStream(file)
+            .on("data", (chunk) => hash.update(chunk))
+            .on("error", reject)
+            .on("end", () => resolve(hash.digest("hex")));
+    });
+}
+export async function hashFiles(root, paths) {
+    const out = {};
+    for (const path of paths)
+        out[path] = await hashFile(join(root, path));
+    return out;
+}

package/dist/login.js

@@ -0,0 +1,145 @@
+// "Login with Pirol", the same flow as `kyte login`: the browser opens the
+// Pirol consent page, a one-time code comes back to a loopback address
+// (127.0.0.1, random port) and is exchanged for a Pirol key. PKCE ties the
+// code to this process. --manual prints the URL and takes the pasted code,
+// for SSH sessions without a browser.
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+export const CLI_AUTH_URL = process.env.PIROL_CLI_AUTH_URL ?? "https://pirol.ai/cli-auth";
+export const PIROL_API = process.env.PIROL_API_BASE_URL ?? "https://api.pirol.ai";
+const TIMEOUT_MS = 180_000;
+export function randomVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+export function pkceChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+export function authUrl(challenge, redirectUri) {
+    const url = new URL(CLI_AUTH_URL);
+    url.searchParams.set("redirect_uri", redirectUri);
+    url.searchParams.set("app_name", "nido");
+    url.searchParams.set("code_challenge", challenge);
+    return url.toString();
+}
+/** The code from a callback URL, or the code itself when pasted alone. */
+export function codeFrom(input) {
+    const text = input.trim();
+    if (!text.includes("?") && !text.includes("=")) {
+        if (!text)
+            throw new Error("No code given");
+        return text;
+    }
+    const params = new URLSearchParams(text.slice(text.indexOf("?") + 1));
+    const error = params.get("error");
+    if (error)
+        throw new Error(params.get("error_description") ?? error);
+    const code = params.get("code");
+    if (!code)
+        throw new Error("The callback contains no code");
+    return code;
+}
+function page(title, body) {
+    return `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:system-ui;margin:3rem;max-width:34rem;line-height:1.5"><h2>${title}</h2><p>${body}</p></body>`;
+}
+function startReceiver() {
+    return new Promise((resolve, reject) => {
+        let settle;
+        const code = new Promise((ok, fail) => (settle = { ok, fail }));
+        code.catch(() => { });
+        let done = false;
+        const finish = (fn) => {
+            if (!done) {
+                done = true;
+                fn();
+            }
+        };
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback")
+                return void res.writeHead(404).end();
+            try {
+                const value = codeFrom(url.toString());
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Logged in ✓", "You can close this window and go back to the terminal."));
+                finish(() => settle.ok(value));
+            }
+            catch (err) {
+                res.writeHead(400, { "content-type": "text/html; charset=utf-8" }).end(page("Login failed", String(err.message)));
+                finish(() => settle.fail(err));
+            }
+        });
+        const timer = setTimeout(() => {
+            finish(() => settle.fail(new Error("The browser did not come back in time")));
+            server.close();
+        }, TIMEOUT_MS);
+        timer.unref();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string")
+                return reject(new Error("Could not open a local port"));
+            resolve({
+                redirectUri: `http://127.0.0.1:${addr.port}/callback`,
+                code,
+                close() {
+                    clearTimeout(timer);
+                    finish(() => settle.fail(new Error("cancelled")));
+                    server.close();
+                },
+            });
+        });
+    });
+}
+export function browserCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { cmd: "open", args: [url] };
+    if (platform === "win32")
+        return { cmd: "cmd.exe", args: ["/c", "start", "", url.replace(/&/g, "^&")] };
+    return { cmd: "xdg-open", args: [url] };
+}
+function openBrowser(url) {
+    return new Promise((resolve) => {
+        try {
+            const { cmd, args } = browserCommand(url);
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            child.on("error", () => resolve(false));
+            child.on("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+export async function loginWithPirol(opts) {
+    const verifier = randomVerifier();
+    const challenge = pkceChallenge(verifier);
+    let code;
+    if (opts.manual) {
+        process.stderr.write(`Open this page in a browser:\n\n  ${authUrl(challenge, "http://127.0.0.1:1/callback")}\n\n`);
+        code = codeFrom(await opts.ask("Paste the code (or the whole callback URL): "));
+    }
+    else {
+        const receiver = await startReceiver();
+        try {
+            const url = authUrl(challenge, receiver.redirectUri);
+            const opened = await openBrowser(url);
+            process.stderr.write(opened ? "Browser opened. Confirm the login there…\n" : `Open this page in a browser:\n\n  ${url}\n\n`);
+            code = await receiver.code;
+        }
+        finally {
+            receiver.close();
+        }
+    }
+    const res = await fetch(`${PIROL_API}/v1/auth/exchange`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code, code_verifier: verifier }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.key)
+        throw new Error(`Login failed: ${body.error?.message ?? `HTTP ${res.status}`}`);
+    return { key: body.key, email: body.email ?? "" };
+}

package/dist/manifest.js

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export const MANIFEST = "nido.json";
+export const AGENTS = ["claude"];
+/**
+ * OpenShell community image with Claude Code, Codex and OpenCode, used until
+ * our own `coding` template exists. Pinned, and pre-pulled on every node
+ * (infra/agent-sandbox/versions.env, SANDBOX_IMAGE).
+ */
+export const DEFAULT_IMAGE = "ghcr.io/nvidia/openshell-community/sandboxes/base@sha256:aeef1c63f00e2913ea002ccb3aaf925f338b5c5d70e63576f0d95c16a138044e";
+export function readManifest(dir) {
+    const file = join(dir, MANIFEST);
+    if (!existsSync(file))
+        throw new Error(`No ${MANIFEST} here. Create one with: nido init`);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${MANIFEST} is not valid JSON: ${err.message}`);
+    }
+    return parseManifest(raw, basename(dir));
+}
+export function parseManifest(raw, folderName) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${MANIFEST} must be an object`);
+    const m = raw;
+    const known = ["name", "agent", "task", "command", "image", "files", "secrets", "network", "output"];
+    const unknown = Object.keys(m).filter((key) => !known.includes(key) && !key.startsWith("$"));
+    if (unknown.length)
+        throw new Error(`${MANIFEST}: unknown field ${unknown.map((k) => `"${k}"`).join(", ")}`);
+    const agent = optionalString(m, "agent");
+    if (agent !== undefined && !AGENTS.includes(agent)) {
+        throw new Error(`${MANIFEST}: agent "${agent}" is not supported yet. Use ${AGENTS.join(", ")} or "command".`);
+    }
+    const task = optionalString(m, "task");
+    const command = m.command;
+    if (command !== undefined && typeof command !== "string" && !isStringArray(command)) {
+        throw new Error(`${MANIFEST}: "command" must be a string or a list of strings`);
+    }
+    if (agent && !task)
+        throw new Error(`${MANIFEST}: "agent" needs a "task"`);
+    if (agent && command !== undefined)
+        throw new Error(`${MANIFEST}: use either "agent" or "command", not both`);
+    if (!agent && command === undefined)
+        throw new Error(`${MANIFEST}: set "agent" and "task", or "command"`);
+    const files = m.files;
+    if (files !== undefined && (typeof files !== "object" || files === null || Array.isArray(files))) {
+        throw new Error(`${MANIFEST}: "files" must be an object like {"exclude": ["node_modules"]}`);
+    }
+    const exclude = files?.exclude ?? [];
+    if (!isStringArray(exclude))
+        throw new Error(`${MANIFEST}: "files.exclude" must be a list of strings`);
+    const output = (optionalString(m, "output") ?? "output/").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!output || output.startsWith("/") || output.split("/").includes("..")) {
+        throw new Error(`${MANIFEST}: "output" must be a folder inside this folder`);
+    }
+    return {
+        name: sandboxName(optionalString(m, "name") ?? folderName),
+        agent: agent,
+        task,
+        command: command,
+        image: optionalString(m, "image") ?? DEFAULT_IMAGE,
+        imageSet: m.image !== undefined,
+        exclude,
+        secrets: stringList(m, "secrets"),
+        network: stringList(m, "network"),
+        output,
+    };
+}
+/** Sandbox names are DNS labels: lowercase letters, digits and dashes. */
+export function sandboxName(input) {
+    const name = input
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    return name || "nest";
+}
+function optionalString(m, key) {
+    const value = m[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${MANIFEST}: "${key}" must be a non-empty string`);
+    return value;
+}
+function stringList(m, key) {
+    const value = m[key] ?? [];
+    if (!isStringArray(value))
+        throw new Error(`${MANIFEST}: "${key}" must be a list of strings`);
+    return value;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+export function manifestTemplate(agent) {
+    const body = agent === "claude"
+        ? {
+            agent: "claude",
+            task: "Read the files in this folder and write a short summary to output/summary.md",
+            files: { exclude: ["node_modules", ".venv", "*.log"] },
+            secrets: ["anthropic"],
+            output: "output/",
+        }
+        : {
+            command: "mkdir -p output && ls -la > output/files.txt && uname -a >> output/files.txt",
+            files: { exclude: ["node_modules", ".venv", "*.log"] },
+            output: "output/",
+        };
+    return JSON.stringify(body, null, 2) + "\n";
+}

package/dist/paths.js

@@ -0,0 +1,6 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Everything nido keeps on this machine lives here. */
+export function nidoHome() {
+    return process.env.NIDO_HOME ?? join(homedir(), ".nido");
+}

package/dist/run.js

@@ -0,0 +1,12 @@
+import { spawn } from "node:child_process";
+export function run(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+        child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}

package/dist/secrets.js

@@ -0,0 +1,30 @@
+// Secret names in nido map to OpenShell provider profiles. A profile says
+// which env var holds the value and which hosts may receive it. The value
+// stays in the gateway; the sandbox only sees a placeholder.
+export const SECRET_KINDS = {
+    anthropic: {
+        profile: "claude-code",
+        envVar: "ANTHROPIC_API_KEY",
+        hosts: ["api.anthropic.com", "statsig.anthropic.com", "sentry.io"],
+        hint: "Anthropic API key (console.anthropic.com → API keys)",
+    },
+    openai: {
+        profile: "openai",
+        envVar: "OPENAI_API_KEY",
+        hosts: ["api.openai.com"],
+        hint: "OpenAI API key",
+    },
+    github: {
+        profile: "github",
+        envVar: "GITHUB_TOKEN",
+        hosts: ["api.github.com", "github.com"],
+        hint: "GitHub token (or use --from-gh)",
+    },
+};
+export function secretKind(name) {
+    const kind = SECRET_KINDS[name];
+    if (!kind) {
+        throw new Error(`Unknown secret "${name}". Supported for now: ${Object.keys(SECRET_KINDS).join(", ")}`);
+    }
+    return kind;
+}

package/dist/sync.js

@@ -0,0 +1,56 @@
+// Decides what goes up and what comes back. Pure functions, so the rules
+// are easy to test: upload only changes, never overwrite a file the user
+// changed locally since the last download.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+export const STATE_FILE = ".nido/state.json";
+export function readState(dir, sandbox) {
+    const empty = { sandbox, uploaded: {}, downloaded: {} };
+    const file = join(dir, STATE_FILE);
+    if (!existsSync(file))
+        return empty;
+    try {
+        const state = JSON.parse(readFileSync(file, "utf8"));
+        // A different sandbox has none of our files yet. Downloads stay valid,
+        // they describe the local folder.
+        return state.sandbox === sandbox ? state : { ...empty, downloaded: state.downloaded ?? {} };
+    }
+    catch {
+        return empty;
+    }
+}
+export function writeState(dir, state) {
+    const file = join(dir, STATE_FILE);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+}
+export function planUpload(local, uploaded) {
+    return {
+        changed: Object.keys(local).filter((path) => uploaded[path] !== local[path]).sort(),
+        removed: Object.keys(uploaded).filter((path) => !(path in local)).sort(),
+    };
+}
+/**
+ * remote: files in the sandbox's output folder.
+ * local: the same paths in the local folder (missing = not there).
+ * downloaded: what we wrote last time.
+ */
+export function planDownload(remote, local, downloaded) {
+    return Object.keys(remote)
+        .sort()
+        .map((path) => {
+        const here = local[path];
+        if (here === undefined)
+            return { path, kind: "new" };
+        if (here === remote[path])
+            return { path, kind: "same" };
+        if (here === downloaded[path])
+            return { path, kind: "update" };
+        return { path, kind: "conflict", savedAs: conflictName(path) };
+    });
+}
+/** report.md → report.remote.md, so the copy opens in the same app. */
+export function conflictName(path) {
+    const ext = extname(path);
+    return ext && !path.endsWith(`/${ext}`) ? `${path.slice(0, -ext.length)}.remote${ext}` : `${path}.remote`;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@pirol/nido",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Run agents in isolated sandboxes. Give it a folder, get results back.",
+  "type": "module",
+  "bin": {
+    "nido": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.9"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://pirol.ai/docs/sandboxes",
+  "keywords": [
+    "sandbox",
+    "agents",
+    "claude",
+    "kata",
+    "openshell"
+  ]
+}