promigence 0.1.0-beta.12

package/dist/sdk/warm.js

@@ -0,0 +1,40 @@
+import { isIP } from "node:net";
+import { DEFAULT_API_URL } from "./core.js";
+import { PromigenceClient, isKeyedCreate, newIdempotencyKey, serverAppMs } from "./client.js";
+import { warmTransport } from "./http2.js";
+import { Sandbox } from "./sandbox.js";
+import { untraced } from "./trace.js";
+function quietly(f) {
+    try {
+        const r = f();
+        if (r instanceof Promise)
+            r.catch(() => { });
+    }
+    catch {
+    }
+}
+export function warmUp() {
+    try {
+        untraced(() => {
+            quietly(() => newIdempotencyKey());
+            quietly(() => isKeyedCreate("POST", "/runs?wait_ms=1"));
+            quietly(() => serverAppMs("app;dur=1.00"));
+            quietly(() => warmTransport());
+            quietly(() => { isIP("a.b"); isIP("a.b"); });
+            let client;
+            quietly(() => { client = new PromigenceClient({ apiKey: "warm", apiUrl: DEFAULT_API_URL }); });
+            if (client === undefined)
+                return;
+            const c = client;
+            quietly(() => c.request(undefined));
+            quietly(() => c.runs.start(undefined));
+            quietly(() => c.sandboxes.exec("sbx_0", undefined));
+            quietly(() => Sandbox.create({ client: c, tier: "small" }));
+            quietly(() => Sandbox.forkHandlesWith("", undefined, {}));
+            const make = Sandbox;
+            quietly(() => new make({ sandboxId: "sbx_0", runId: "run_0", snapshot: "", client: c }).commands.run("", null));
+        });
+    }
+    catch {
+    }
+}

package/dist/ssh.js

@@ -0,0 +1,267 @@
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isIP } from "node:net";
+import { delimiter, join, resolve } from "node:path";
+import { PromigenceClient, PromigenceError, configDir } from "./sdk/index.js";
+import { bool, client, clientOpts, nexts, positional, str } from "./commands.js";
+import { emit, exitWith, okEnvelope, recordNotice, usageError, write } from "./io.js";
+import { sh, shellArg } from "./term.js";
+const SANDBOX_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const SSH_USER = /^[a-z_][a-z0-9_-]{0,31}$/;
+const HOST_LABEL = /^[A-Za-z0-9_](?:[A-Za-z0-9_-]{0,61}[A-Za-z0-9_])?$/;
+export function validSshHost(host) {
+    if (isIP(host) !== 0)
+        return true;
+    if (host.length === 0 || host.length > 253)
+        return false;
+    return host.split(".").every((label) => HOST_LABEL.test(label));
+}
+export const validSshUser = (user) => SSH_USER.test(user);
+export function sshSandboxId(sid) {
+    if (!SANDBOX_ID.test(sid)) {
+        throw usageError(`'${sid}' is not a sandbox id`, "Pass the id as the API shows it, e.g. promigence sandbox ssh sbx_01 (see promigence sandbox list).");
+    }
+    return sid;
+}
+function badAccess(what) {
+    return new PromigenceError({
+        code: "internal",
+        message: `the API's ssh access answer has ${what}; nothing was written or run`,
+        fix: "Not your fault. Check PROMIGENCE_API_URL points at the Promigence API; if it does, report it with promigence --version.",
+        exitCode: 1,
+    });
+}
+export function checkSshAccess(access) {
+    if (typeof access.host !== "string" || !validSshHost(access.host))
+        throw badAccess("a host that is not a hostname or an address");
+    if (typeof access.user !== "string" || !validSshUser(access.user))
+        throw badAccess("a login name outside [a-z_][a-z0-9_-]");
+    for (const [name, v] of [["host key", access.host_key], ["access credential", access.token]]) {
+        if (typeof v !== "string" || v.trim() === "" || /[\r\n\0]/.test(v))
+            throw badAccess(`a ${name} that is empty or spans lines`);
+    }
+    return access;
+}
+export const sshDir = (sandboxId) => join(configDir(), "ssh", sandboxId);
+const paths = (sandboxId) => {
+    const dir = sshDir(sandboxId);
+    return {
+        dir,
+        keyPath: join(dir, "id_ed25519"),
+        knownHosts: join(dir, "known_hosts"),
+        tokenPath: join(dir, "token"),
+        apiUrlPath: join(dir, "api_url"),
+    };
+};
+function ensureKey(p) {
+    mkdirSync(p.dir, { recursive: true, mode: 0o700 });
+    chmodSync(p.dir, 0o700);
+    if (!existsSync(`${p.keyPath}.pub`)) {
+        rmSync(p.keyPath, { force: true });
+        const r = spawnSync("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "promigence", "-f", p.keyPath], { stdio: ["ignore", "ignore", "pipe"] });
+        if (r.status !== 0) {
+            throw usageError(`ssh-keygen failed: ${String(r.stderr ?? "").trim() || "not found"}`, "Install OpenSSH (`ssh-keygen` must be on PATH), or pass --key PATH to use a key you already have.");
+        }
+    }
+    return readFileSync(`${p.keyPath}.pub`, "utf8").trim();
+}
+async function open(ctx, sandboxId) {
+    const local = paths(sandboxId);
+    const keyFlag = str(ctx, "--key");
+    let publicKey;
+    if (keyFlag) {
+        const pub = keyFlag.endsWith(".pub") ? keyFlag : `${keyFlag}.pub`;
+        if (!existsSync(pub)) {
+            throw usageError(`no public key at ${pub}`, "Pass --key PATH pointing at an ssh-ed25519 private key; its .pub must be beside it.");
+        }
+        publicKey = readFileSync(pub, "utf8").trim();
+        local.keyPath = resolve(pub.replace(/\.pub$/, ""));
+        mkdirSync(local.dir, { recursive: true, mode: 0o700 });
+    }
+    else {
+        publicKey = ensureKey(local);
+    }
+    const ttl = str(ctx, "--ttl");
+    const idle = str(ctx, "--idle");
+    const num = (v, flag) => {
+        if (v === undefined)
+            return undefined;
+        const n = Number(v);
+        if (!Number.isFinite(n) || n <= 0)
+            throw usageError(`${flag} must be a number of seconds`, `e.g. ${flag} 900.`);
+        return Math.floor(n);
+    };
+    const c = client(ctx);
+    const access = checkSshAccess(await c.sandboxes.ssh.open(sandboxId, {
+        publicKey,
+        ...(num(ttl, "--ttl") === undefined ? {} : { ttlS: num(ttl, "--ttl") }),
+        ...(num(idle, "--idle") === undefined ? {} : { idleTimeoutS: num(idle, "--idle") }),
+    }));
+    writeFileSync(local.knownHosts, `${access.host} ${access.host_key}\n`, { mode: 0o600 });
+    writeFileSync(local.tokenPath, `${access.token}\n`, { mode: 0o600 });
+    chmodSync(local.tokenPath, 0o600);
+    writeFileSync(local.apiUrlPath, `${c.apiUrl}\n`, { mode: 0o600 });
+    return { access, local };
+}
+export const winArg = (value) => /^[A-Za-z0-9_.:\\/@,=-]+$/.test(value) ? value : `"${value.replace(/"/g, '\\"')}"`;
+const configPath = (path, platform) => platform === "win32" || /\s/.test(path) ? `"${path}"` : path;
+export const proxyCommand = (self, sandboxId, platform = process.platform) => `${self} sandbox ssh ${platform === "win32" ? winArg(sandboxId) : shellArg(sandboxId)} --proxy`;
+function sshArgs(sid, local, self, platform = process.platform) {
+    return [
+        "-i",
+        local.keyPath,
+        "-o",
+        "IdentitiesOnly=yes",
+        "-o",
+        `UserKnownHostsFile=${configPath(local.knownHosts, platform)}`,
+        "-o",
+        "StrictHostKeyChecking=yes",
+        "-o",
+        `ProxyCommand=${proxyCommand(self, sid, platform)}`,
+    ];
+}
+export function selfCommand(platform = process.platform, argv1 = process.argv[1] ?? "", execPath = process.execPath) {
+    if (platform === "win32")
+        return `"${execPath}" "${argv1}"`;
+    if (/promigence$/.test(argv1) && !argv1.endsWith(".js") && onPathIsThis(argv1))
+        return "promigence";
+    return `${shellArg(execPath)} ${shellArg(argv1)}`;
+}
+function onPathIsThis(self) {
+    try {
+        const mine = realpathSync(self);
+        for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
+            if (!dir)
+                continue;
+            const cand = join(dir, "promigence");
+            if (existsSync(cand))
+                return realpathSync(cand) === mine;
+        }
+    }
+    catch {
+    }
+    return false;
+}
+export const configBlock = (sid, access, local, self, platform = process.platform) => [
+    `Host ${access.host}`,
+    `  User ${access.user}`,
+    `  IdentityFile ${configPath(local.keyPath, platform)}`,
+    `  IdentitiesOnly yes`,
+    `  UserKnownHostsFile ${configPath(local.knownHosts, platform)}`,
+    `  StrictHostKeyChecking yes`,
+    `  ProxyCommand ${proxyCommand(self, sid, platform)}`,
+    "",
+].join("\n");
+export const sshConfigHint = (sid, platform = process.platform) => platform === "win32"
+    ? `New-Item -ItemType Directory -Force $HOME\\.ssh | Out-Null; ${sh `promigence sandbox ssh ${sid} --config`} | Out-File -Append -Encoding ascii $HOME\\.ssh\\config`
+    : `mkdir -p -m 700 ~/.ssh && ${sh `promigence sandbox ssh ${sid} --config`} >> ~/.ssh/config && chmod 600 ~/.ssh/config`;
+async function proxy(ctx, sandboxId) {
+    const local = paths(sandboxId);
+    let token;
+    if (existsSync(local.tokenPath))
+        token = readFileSync(local.tokenPath, "utf8").trim();
+    const issuedBy = token && existsSync(local.apiUrlPath) ? readFileSync(local.apiUrlPath, "utf8").trim() : "";
+    const c = issuedBy
+        ? new PromigenceClient({ ...clientOpts(ctx), apiUrl: issuedBy, onNotice: recordNotice })
+        : client(ctx);
+    const tunnel = await c.sandboxes.ssh.connect(sandboxId, {
+        ...(token ? { token } : {}),
+        onData: (d) => {
+            process.stdout.write(d);
+        },
+        onClose: () => {
+        },
+    });
+    process.stdin.on("data", (d) => tunnel.write(new Uint8Array(d)));
+    process.stdin.on("end", () => tunnel.close());
+    process.stdin.resume();
+    await tunnel.done;
+    return 0;
+}
+export async function proxyRefusal(ctx, sid, e) {
+    if (!(e instanceof PromigenceError) || e.code !== "auth" || !existsSync(paths(sid).tokenPath))
+        return e;
+    const state = await client(ctx).sandboxes.get(sid).then((s) => s.state).catch(() => undefined);
+    const again = sh `promigence sandbox ssh ${sid}`;
+    const [message, fix] = state === "ended"
+        ? [`sandbox ${sid} has ended`, "Start a new sandbox (promigence fork --count 1 --cap 1) and connect to that one."]
+        : state === undefined
+            ? [`this ssh access to ${sid} was revoked or has expired, or the sandbox has ended`, `Run \`${again}\` again for new access (\`${sh `promigence sandbox info ${sid}`}\` shows whether it is still running).`]
+            : [`this ssh access to ${sid} was revoked or has expired`, `Run \`${again}\` again for new access.`];
+    return new PromigenceError({
+        code: e.code, message, fix, exitCode: e.cliExit,
+        ...(e.status === undefined ? {} : { status: e.status }),
+    });
+}
+async function listAccess(ctx, sid) {
+    const r = await client(ctx).sandboxes.ssh.list(sid);
+    const next = r.keys.length
+        ? nexts([sh `promigence sandbox ssh ${sid} --revoke KEY_ID`, "end one key's access early: put its key_id from this list in place of KEY_ID"])
+        : nexts([sh `promigence sandbox ssh ${sid}`, "new access"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [
+        `ssh access to ${sid}: ${r.keys.length} key(s)`,
+        ...r.keys.map((k) => `  ${k.key_id}  ${k.fingerprint}  expires ${k.expires_at}${k.token_active ? "" : "  (access credential ended)"}`),
+    ], 0, ctx.pointer);
+}
+async function revokeAccess(ctx, sid, keyId) {
+    const r = await client(ctx).sandboxes.ssh.revoke(sid, keyId);
+    const next = nexts([sh `promigence sandbox ssh ${sid} --list`, "the access that is left"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [
+        r.revoked ? `revoked ${r.key_id} on ${sid}` : `${r.key_id} on ${sid} had no access left to revoke`,
+    ], 0, ctx.pointer);
+}
+export const sandboxSsh = async (ctx) => {
+    const sid = sshSandboxId(positional(ctx, "a sandbox id", "promigence sandbox ssh sbx_01"));
+    if (bool(ctx, "--proxy")) {
+        let code;
+        try {
+            code = await proxy(ctx, sid);
+        }
+        catch (e) {
+            throw await proxyRefusal(ctx, sid, e);
+        }
+        return exitWith(code);
+    }
+    if (bool(ctx, "--list"))
+        return listAccess(ctx, sid);
+    const revoke = str(ctx, "--revoke");
+    if (revoke !== undefined)
+        return revokeAccess(ctx, sid, revoke);
+    const { access, local } = await open(ctx, sid);
+    const self = selfCommand();
+    const next = nexts([sshConfigHint(sid), "attach an IDE, scp or rsync"], [sh `promigence sandbox ssh ${sid} --revoke ${access.key_id}`, "end this access early"]);
+    if (bool(ctx, "--config")) {
+        const block = configBlock(sid, access, local, self);
+        if (ctx.explicitMode !== "json") {
+            await write(process.stdout, block);
+            await write(process.stderr, `  next: ${next[0].cmd}\n  then: ssh ${access.host}\n`);
+            return exitWith(0);
+        }
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...access, ssh_config: block }, next), block.split("\n"), 0, ctx.pointer);
+    }
+    const sshLine = ["ssh", ...sshArgs(sid, local, self), `${access.user}@${access.host}`].map(process.platform === "win32" ? winArg : shellArg).join(" ");
+    const details = [
+        `  host key   ${access.host_key_fingerprint}`,
+        `  key        ${access.fingerprint} (${access.key_id})`,
+        `  expires    ${access.expires_at}, idle timeout ${access.idle_timeout_s}s`,
+    ];
+    if (bool(ctx, "--print") && ctx.explicitMode !== "json") {
+        await write(process.stdout, `${sshLine}\n`);
+        await write(process.stderr, `${details.join("\n")}\n`);
+        return exitWith(0);
+    }
+    const runRemote = ctx.cmdTail.length > 0 && ctx.explicitMode !== "json";
+    if (bool(ctx, "--print") || (ctx.mode === "json" && !runRemote)) {
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...access }, next), [sshLine, ...details], 0, ctx.pointer);
+    }
+    const args = [...sshArgs(sid, local, self), `${access.user}@${access.host}`, ...ctx.cmdTail];
+    const child = spawn("ssh", args, { stdio: "inherit" });
+    const code = await new Promise((resolve) => {
+        child.on("error", () => resolve(125));
+        child.on("exit", (c, sig) => resolve(c ?? (sig ? 128 : 125)));
+    });
+    return exitWith(code);
+};
+export const SSH_HANDLERS = {
+    "sandbox ssh": sandboxSsh,
+};

package/dist/surface.d.ts

@@ -0,0 +1,95 @@
+import { VERSION, DOCS_URL } from "./sdk/index.js";
+export { VERSION, DOCS_URL };
+export declare const SCHEMA: "promigence.cli/v1";
+export declare const GUIDE_POINTER = "AI agents: run 'promigence agent-guide' (~1.4k tokens) before using this tool.";
+export declare const DESCRIPTION = "Promigence \u2014 verified, reproducible, forkable execution environments for agents.";
+export declare const GOLDEN_PATH = "promigence run --snapshot promigence/base --count 2 --cap 1 --json -- python3 -c 'print(6*7)'";
+export declare const WAIT_TIMEOUT_DEFAULT = "100s";
+export declare const REQUEST_TIMEOUT_DEFAULT = "30s";
+export declare const LIVE_COMMANDS: readonly ["login", "signup", "logout", "auth login", "keys list", "keys create", "keys revoke", "org list", "org create", "org switch", "org members", "org invite", "org invites", "org uninvite", "org resend", "org role", "org remove", "org leave", "org join", "org audit", "org rename", "org delete", "project list", "project create", "project rename", "project delete", "project cap", "project move", "me", "billing card", "doctor", "ping", "init", "examples", "templates", "templates show", "agent-guide", "mcp", "snapshot create", "snapshot status", "snapshot list", "snapshot inspect", "snapshot verify", "snapshot export", "fork", "exec", "exec output", "exec ps", "exec kill", "files put", "files get", "files ls", "run", "run quote", "run report", "run status", "run cancel", "run kill", "run replay", "run open", "run captures", "sandbox kill", "sandbox shell", "sandbox ssh", "sandbox network", "port expose", "port list", "port revoke", "secrets set", "bench burst", "status", "billing usage", "billing portal", "snapshot delete", "snapshot builds", "snapshot alias", "run list", "sandbox list", "sandbox info", "sandbox pause", "sandbox resume", "sandbox extend", "sandbox probe", "files rm", "secrets list", "secrets delete", "image resolve", "sandbox snapshot", "files search", "files mkdir", "files mv", "files cp", "files chmod", "exec stdin", "sandbox autopause", "agent start", "referrals", "referrals apply", "credits", "credits claim", "runners github", "runners gitlab", "pricing", "github connect", "github status", "github disconnect", "github untrack", "repos", "gitlab connect", "gitlab status", "gitlab disconnect", "gitlab untrack", "billing history"];
+export declare const GUIDE_COMMON_ERRORS: readonly ["auth", "credit_unclaimed", "not_found", "not_verified", "cap_exceeded", "timeout", "nonzero_exit"];
+export type Group = "Setup" | "Snapshots" | "Runs" | "Sandboxes" | "Ops";
+export type CommandStatus = "planned" | "released";
+export interface Flag {
+    name: string;
+    arg?: string;
+    summary: string;
+    repeatable?: boolean;
+    required?: boolean;
+    hidden?: boolean;
+}
+export interface Command {
+    name: string;
+    group: Group;
+    summary: string;
+    args?: string;
+    flags: Flag[];
+    status: CommandStatus;
+    next: string[];
+    helpRow?: {
+        key: string;
+        summary: string;
+        via?: string;
+    };
+    noGuidePointer?: boolean;
+    notOnHosted?: string;
+    passthroughExit?: number;
+    autoIdempotencyKey?: boolean;
+    signIn?: string;
+    note?: string;
+    ownExtraWords?: true;
+}
+export declare const TIER_NOTE = "a sandbox has its snapshot's size (base: small); another size: snapshot create --image REF --tier T";
+export declare const BACKGROUND_NOTE = "background commands started with `exec --background` are ended; anything else you started keeps running when the sandbox resumes";
+export declare const COMMANDS: readonly Command[];
+export declare function compactNames(names: readonly string[]): string;
+export declare const LISTED_COMMANDS: readonly Command[];
+export declare const LIVE_SUMMARY: string;
+export declare const NOT_LIVE_SUMMARY = "";
+export declare const STATUS_LINE: string;
+export declare const GROUPS: readonly Group[];
+export declare const GLOBAL_FLAGS: readonly Flag[];
+export declare function knownFlags(cmd: Command): Set<string>;
+export declare function unknownFlags(cmd: Command, typed: Iterable<string>): string[];
+export declare function nearestFlag(typo: string, cmd: Command): string | undefined;
+export interface ExitCode {
+    code: number;
+    name: string;
+    summary: string;
+}
+export declare const EXIT_CODES: readonly ExitCode[];
+export declare const EXIT_PRECEDENCE: readonly number[];
+export declare const EXIT_PRECEDENCE_TEXT = "2 > 5 > 6 > 7/8/9/10 > 11 > 3 > 12 > 4 > 1 > 0";
+export declare const OUTPUT_MODE_PRECEDENCE: readonly ["--json | --text", "PROMIGENCE_OUTPUT=json|text", "stdout TTY → text, else json"];
+export interface NextHint {
+    cmd: string;
+    why: string;
+}
+export interface EnvelopeError {
+    code: string;
+    message: string;
+    fix: string;
+    docs: string;
+    guide: string;
+    request_id?: string;
+    category?: string;
+    retryable?: boolean;
+    exit?: number;
+}
+export interface Envelope {
+    schema: typeof SCHEMA;
+    command: string;
+    ok: boolean;
+    error?: EnvelopeError;
+    next: NextHint[];
+    idempotent_replay?: boolean;
+    hint?: string;
+    promigence_exit?: number;
+    [extra: string]: unknown;
+}
+export declare function findCommand(words: readonly string[]): Command | undefined;
+export declare function renderHelp(): string;
+export declare function signInLine(c: Pick<Command, "signIn">): string | undefined;
+export declare function renderCommandHelp(c: Command): string;
+export declare function notReleasedEnvelope(c: Command): Envelope;
+export declare function notReleasedLines(c: Command, env: Envelope): string[];