@tealbrick/avm 0.1.0

package/dist/client/index.js

@@ -0,0 +1,364 @@
+import { administrationArgv } from "./administration.js";
+export { avmConfigSchema, connectionSchema, policySchema, administrationSchema, } from "./config.js";
+export const AVMM_COMPATIBILITY = {
+    version: "0.13.0-alpha.2",
+    revision: "75078743b9bfc2ba268f1fdeea74f298983dfac4",
+};
+import { spawn } from "node:child_process";
+/** Errors intentionally exclude command arguments, remote messages, stdout and stderr. */
+export class AvmError extends Error {
+    code;
+    exitCode;
+    constructor(code, exitCode) {
+        super(`AgentVM ${code.toLowerCase().replaceAll("_", " ")}`);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.name = "AvmError";
+    }
+}
+const identifier = (value) => {
+    if (typeof value !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(value))
+        throw new AvmError("INVALID_REQUEST");
+    return value;
+};
+const limit = (value = 50) => {
+    if (!Number.isInteger(value) || value < 1 || value > 200)
+        throw new AvmError("INVALID_REQUEST");
+    return String(value);
+};
+export function commandArgv(request, policy = {}) {
+    const prefix = ["--json"];
+    switch (request.operation) {
+        case "configured": {
+            const grant = policy.administration?.find((g) => g.name === identifier(request.action));
+            if (!grant)
+                throw new AvmError("DENIED");
+            try {
+                return [...prefix, ...administrationArgv(grant.request)];
+            }
+            catch {
+                throw new AvmError("INVALID_REQUEST");
+            }
+        }
+        case "poolStatus":
+        case "poolPressure":
+        case "poolQueue":
+            return [...prefix, "pool", request.operation.slice(4).toLowerCase()];
+        case "poolPolicy":
+            return [...prefix, "pool", "policy", "show"];
+        case "workspaces":
+            return [...prefix, "workspace", "ls"];
+        case "users":
+            return [...prefix, "user", "ls"];
+        case "workspace":
+            if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(request.id))
+                throw new AvmError("INVALID_REQUEST");
+            return [...prefix, "workspace", "show", request.id];
+        case "user":
+            return [...prefix, "user", "show", identifier(request.id)];
+        case "owner":
+            return [...prefix, "agent", "owner", "get", identifier(request.worker)];
+        case "shares":
+            return [...prefix, "agent", "share", "ls", identifier(request.worker)];
+        case "resident":
+            return [...prefix, "agent", "resident", "get"];
+        case "ingress":
+            return [
+                ...prefix,
+                "ingress",
+                "ls",
+                ...(request.worker ? ["--agent", identifier(request.worker)] : []),
+            ];
+        case "doctor":
+        case "inventory":
+            return [...prefix, request.operation];
+        case "workers":
+            return [...prefix, "worker", "ls"];
+        case "bundles":
+            return [...prefix, "bundle", "ls"];
+        case "monitor":
+            return [...prefix, "monitor", "status"];
+        case "workerStatus":
+            return [...prefix, "worker", "status", identifier(request.worker)];
+        case "capabilities":
+            return [...prefix, "capability", "manifest", identifier(request.worker)];
+        case "runs":
+            return [...prefix, "runs", "ls", "--limit", limit(request.limit)];
+        case "events":
+            return [
+                ...prefix,
+                "events",
+                "--limit",
+                limit(request.limit),
+                ...[
+                    ["--vm", request.worker],
+                    ["--event", request.event],
+                    ["--run-id", request.runId],
+                ].flatMap(([flag, value]) => value === undefined ? [] : [flag, identifier(value)]),
+            ];
+        case "runStatus":
+            return [...prefix, "runs", "status", identifier(request.runId)];
+        case "start":
+        case "stop":
+        case "promote":
+        case "destroy": {
+            const worker = identifier(request.worker);
+            if (!policy.lifecycle?.some((g) => g.worker === worker &&
+                g.operations.includes(request.operation)))
+                throw new AvmError("DENIED");
+            return [...prefix, "worker", request.operation, worker];
+        }
+        case "spawn": {
+            const worker = identifier(request.worker);
+            const grant = policy.spawns?.find((g) => g.worker === worker);
+            if (!grant)
+                throw new AvmError("DENIED");
+            if (!["light", "small", "standard", "browser"].includes(grant.profile) ||
+                !["ephemeral", "durable"].includes(grant.mode))
+                throw new AvmError("INVALID_REQUEST");
+            const argv = [
+                ...prefix,
+                "worker",
+                "create",
+                worker,
+                "--profile",
+                grant.profile,
+                "--mode",
+                grant.mode,
+            ];
+            for (const [flag, values] of [
+                ["--harness", grant.harnesses],
+                ["--mcp", grant.mcps],
+                ["--plugin", grant.plugins],
+                ["--bundle", grant.bundles],
+                ["--cap", grant.capabilities],
+            ]) {
+                for (const value of values ?? []) {
+                    if (!/^[A-Za-z0-9@][A-Za-z0-9@_./:+-]{0,255}$/.test(value))
+                        throw new AvmError("INVALID_REQUEST");
+                    argv.push(flag, value);
+                }
+            }
+            for (const value of grant.auth ?? []) {
+                if (!/^[a-z][a-z0-9_-]*=(none|local)$|^codex=shared$/.test(value))
+                    throw new AvmError("INVALID_REQUEST");
+                argv.push("--auth", value);
+            }
+            return argv;
+        }
+        case "exec": {
+            const worker = identifier(request.worker);
+            const grant = policy.commands?.find((g) => g.worker === worker && g.command === request.command);
+            if (!grant)
+                throw new AvmError("DENIED");
+            if (!grant.argv.length ||
+                grant.argv.some((a) => typeof a !== "string" || a.includes("\0") || a.length > 8192))
+                throw new AvmError("INVALID_REQUEST");
+            return [...prefix, "worker", "exec", worker, "--", ...grant.argv];
+        }
+        default:
+            throw new AvmError("INVALID_REQUEST");
+    }
+}
+export class AvmClient {
+    transport;
+    policy;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.policy = structuredClone(options.policy ?? {});
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        if (!Number.isInteger(this.timeoutMs) ||
+            this.timeoutMs < 1 ||
+            this.timeoutMs > 300_000)
+            throw new AvmError("INVALID_REQUEST");
+    }
+    timeoutMs;
+    async request(request, options = {}) {
+        const argv = commandArgv(request, this.policy);
+        if (options.signal?.aborted)
+            throw new AvmError("CANCELLED");
+        const controller = new AbortController();
+        let rejectAbort = () => { };
+        const aborted = new Promise((_, reject) => {
+            rejectAbort = reject;
+        });
+        const abort = (code) => {
+            controller.abort();
+            rejectAbort(new AvmError(code));
+        };
+        const onAbort = () => abort("CANCELLED");
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(() => abort("TIMEOUT"), this.timeoutMs);
+        try {
+            const raw = await Promise.race([
+                this.transport.run(argv, { signal: controller.signal }),
+                aborted,
+            ]);
+            let envelope;
+            try {
+                envelope = JSON.parse(raw.stdout);
+            }
+            catch {
+                throw new AvmError(raw.exitCode ? "TRANSPORT" : "PROTOCOL", raw.exitCode);
+            }
+            if (!envelope ||
+                typeof envelope !== "object" ||
+                Array.isArray(envelope) ||
+                envelope.api_version !== "agentvm/v1")
+                throw new AvmError("PROTOCOL");
+            const response = envelope;
+            if ("error" in response)
+                throw new AvmError("REMOTE", raw.exitCode);
+            if (!("result" in response))
+                throw new AvmError("PROTOCOL");
+            if (request.operation === "exec") {
+                const result = response.result;
+                if (!result ||
+                    typeof result !== "object" ||
+                    Array.isArray(result) ||
+                    !Number.isInteger(result.returncode) ||
+                    typeof result.stdout !== "string" ||
+                    typeof result.stderr !== "string")
+                    throw new AvmError("PROTOCOL");
+                if (result.returncode !== 0)
+                    throw new AvmError("GUEST_FAILED", result.returncode);
+            }
+            if (raw.exitCode !== 0)
+                throw new AvmError("TRANSPORT", raw.exitCode);
+            return response.result;
+        }
+        catch (error) {
+            if (error instanceof AvmError)
+                throw error;
+            throw new AvmError("TRANSPORT");
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+/** Executes host-owned AVM remotely: operator JSON stdin or paired, quoted ForceCommand protocol. */
+export class SshTransport {
+    target;
+    mode;
+    identityFile;
+    identityTokenFile;
+    command;
+    maxOutputBytes;
+    constructor(options) {
+        if (!/^(?:[A-Za-z0-9_][A-Za-z0-9_.-]*@)?[A-Za-z0-9][A-Za-z0-9.-]*$/.test(options.target))
+            throw new AvmError("INVALID_REQUEST");
+        this.mode = options.mode ?? "operator";
+        if (!["operator", "paired"].includes(this.mode))
+            throw new AvmError("INVALID_REQUEST");
+        for (const path of [options.identityFile, options.identityTokenFile])
+            if (path !== undefined &&
+                (!/^\/[A-Za-z0-9_./ -]+$/.test(path) || path.length > 4096))
+                throw new AvmError("INVALID_REQUEST");
+        if (this.mode === "paired" &&
+            (!options.target.startsWith("agentvm-client@") ||
+                !options.identityFile ||
+                options.sudo ||
+                options.identityTokenFile))
+            throw new AvmError("INVALID_REQUEST");
+        this.identityFile = options.identityFile;
+        this.identityTokenFile = options.identityTokenFile;
+        this.target = options.target;
+        this.maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
+        if (!Number.isInteger(this.maxOutputBytes) ||
+            this.maxOutputBytes < 1024 ||
+            this.maxOutputBytes > 16_777_216)
+            throw new AvmError("INVALID_REQUEST");
+        // This entire remote command is constant; no caller values enter it.
+        this.command = options.sudo
+            ? `/usr/bin/python3 -c 'import json,subprocess,sys;sys.exit(subprocess.call(["sudo","-n","/usr/local/bin/avm"]+json.load(sys.stdin)))'`
+            : `/usr/bin/python3 -c 'import json,subprocess,sys;sys.exit(subprocess.call(["/usr/local/bin/avm"]+json.load(sys.stdin)))'`;
+    }
+    run(argv, { signal }) {
+        if (signal.aborted)
+            return Promise.reject(new AvmError("CANCELLED"));
+        if (argv.some((a) => typeof a !== "string" || a.includes("\0") || a.length > 8192))
+            return Promise.reject(new AvmError("INVALID_REQUEST"));
+        const remoteArgv = this.identityTokenFile
+            ? ["--identity-token-file", this.identityTokenFile, ...argv]
+            : [...argv];
+        const quote = (value) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+        const command = this.mode === "paired"
+            ? "exec /usr/local/bin/avm " + remoteArgv.map(quote).join(" ")
+            : this.command;
+        return new Promise((resolve, reject) => {
+            const child = spawn("/usr/bin/ssh", [
+                ...(this.mode === "paired" ? ["-F", "/dev/null"] : []),
+                "-T",
+                "-o",
+                "ForwardAgent=no",
+                "-o",
+                "ClearAllForwardings=yes",
+                "-o",
+                "PermitLocalCommand=no",
+                "-o",
+                "BatchMode=yes",
+                "-o",
+                "ConnectTimeout=10",
+                "-o",
+                "StrictHostKeyChecking=yes",
+                ...(this.identityFile
+                    ? [
+                        "-o",
+                        "IdentitiesOnly=yes",
+                        "-o",
+                        "IdentityAgent=none",
+                        "-i",
+                        this.identityFile,
+                    ]
+                    : []),
+                "--",
+                this.target,
+                command,
+            ], {
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+                env: { PATH: "/usr/bin:/bin", HOME: process.env.HOME },
+            });
+            const chunks = [];
+            let bytes = 0;
+            let failure;
+            const stop = () => {
+                failure ??= new AvmError("CANCELLED");
+                child.kill("SIGKILL");
+            };
+            signal.addEventListener("abort", stop, { once: true });
+            const collect = (data, keep) => {
+                bytes += data.length;
+                if (bytes > this.maxOutputBytes) {
+                    failure = new AvmError("OUTPUT_LIMIT");
+                    child.kill("SIGKILL");
+                }
+                else if (keep)
+                    chunks.push(data);
+            };
+            child.stdout.on("data", (data) => collect(data, true));
+            child.stderr.on("data", (data) => collect(data, false));
+            child.stdin.on("error", () => { });
+            child.on("error", () => {
+                signal.removeEventListener("abort", stop);
+                reject(new AvmError("TRANSPORT"));
+            });
+            child.on("close", (code) => {
+                signal.removeEventListener("abort", stop);
+                if (failure)
+                    reject(failure);
+                else
+                    resolve({
+                        stdout: Buffer.concat(chunks).toString("utf8"),
+                        exitCode: code ?? 255,
+                    });
+            });
+            child.stdin.end(this.mode === "paired" ? undefined : JSON.stringify(remoteArgv));
+            if (signal.aborted)
+                stop();
+        });
+    }
+}

package/dist/extension/_manifest.json

@@ -0,0 +1,11 @@
+{
+  "kind": "eve-extension",
+  "formatVersion": 2,
+  "builtWithEve": "0.55.0",
+  "requires": {
+    "extension": 1,
+    "tool": 38,
+    "dynamicTool": 37,
+    "config": 1
+  }
+}