@agentproto/sandbox-instabox 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,761 @@
+import { randomBytes } from 'crypto';
+import { SandboxQuotaError, SandboxBoxGoneError, scrubCommandFromMessage } from '@agentproto/sandbox';
+
+/**
+ * @agentproto/sandbox-instabox v0.1.0
+ * InstaBox SandboxProvider for @agentproto/sandbox.
+ */
+
+// src/api.ts
+var InstaboxApiError = class extends Error {
+  status;
+  code;
+  requestId;
+  retryable;
+  operationId;
+  constructor(message, info) {
+    super(message);
+    this.name = "InstaboxApiError";
+    this.status = info.status;
+    this.code = info.code;
+    this.requestId = info.requestId;
+    this.retryable = info.retryable;
+    this.operationId = info.operationId;
+  }
+};
+var DEFAULT_API_URL = "https://api.instabox.sh";
+var REQUEST_TIMEOUT_MS = 3e4;
+var OPERATION_WAIT = "25s";
+var EXEC_HTTP_TIMEOUT_MS = 62e4;
+var OPERATION_TIMEOUT_MS = 3e5;
+var OPERATION_RETRY_BASE_DELAY_MS = 500;
+var CREATE_RETRY_ATTEMPTS = 5;
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function isInstaboxQuotaFailure(status, code, message) {
+  if (status === 402 || status === 403 || status === 429) return true;
+  return /quota|limit/i.test(code) || /quota|limit/i.test(message);
+}
+var InstaboxClient = class {
+  apiKey;
+  apiUrl;
+  fetchImpl;
+  retryDelayMs;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.apiUrl = (opts.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    this.retryDelayMs = opts.retryDelayMs ?? ((attempt) => new Promise((resolve) => setTimeout(resolve, OPERATION_RETRY_BASE_DELAY_MS * attempt)));
+  }
+  async request(method, path, init = {}) {
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.apiUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...init.idempotency ? { "Idempotency-Key": init.idempotency } : {}
+        },
+        ...init.body !== void 0 ? { body: JSON.stringify(init.body) } : {},
+        signal: AbortSignal.timeout(init.serviceTimeoutMs ?? REQUEST_TIMEOUT_MS)
+      });
+    } catch (err) {
+      throw new InstaboxApiError(`instabox: transport failure calling ${method} ${path}`, {
+        status: null,
+        code: "transport_error",
+        retryable: true
+      });
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      const body = safeParse(text);
+      const code = asString(body.error?.code) ?? "http_error";
+      const message = asString(body.error?.message) ?? `${method} ${path} failed with HTTP ${res.status}`;
+      throw new InstaboxApiError(`instabox: ${message}`, {
+        status: res.status,
+        code,
+        requestId: asString(body.error?.requestId),
+        retryable: body.error?.retryable === true || res.status === 429 || res.status >= 500,
+        operationId: asString(body.error?.operationId)
+      });
+    }
+    const raw = await res.json();
+    return raw;
+  }
+  /** POST /v1/machines. Retried on TRANSPORT errors only (idempotency key is
+   *  fixed per instance call, so a retry after a lost response cannot mint a
+   *  duplicate machine). Applied to the network-safe envelope, then the 202
+   *  body is returned. */
+  async createMachine(input, idempotencyKey) {
+    return requestWithTransportRetry(
+      () => this.request("POST", "/v1/machines", { body: input, idempotency: idempotencyKey }),
+      CREATE_RETRY_ATTEMPTS
+    );
+  }
+  /** GET /v1/operations/{id}?wait=25s, with an overall timeout and retryable
+   *  transport-error backoff. */
+  async waitForOperation(operationId, timeoutMs = OPERATION_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 1; ; attempt++) {
+      let op = null;
+      let transportError = false;
+      try {
+        op = await this.request(
+          "GET",
+          `/v1/operations/${encodeURIComponent(operationId)}?wait=${OPERATION_WAIT}`
+        );
+      } catch (err) {
+        if (!isTransportError(err)) throw err;
+        transportError = true;
+      }
+      if (op !== null) {
+        if (op.state === "succeeded") return op;
+        if (op.state === "failed") {
+          throw new InstaboxApiError(describeOperationError(op), {
+            status: null,
+            code: "operation_failed",
+            operationId
+          });
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new InstaboxApiError(
+          `instabox: operation ${operationId} did not settle within ${timeoutMs}ms.`,
+          { status: null, code: "operation_timeout", operationId }
+        );
+      }
+      if (transportError) await this.retryDelayMs(attempt);
+    }
+  }
+  /** GET /v1/machines/{id} (accepts id or name; ports/wake/files need `id`). */
+  getMachine(idOrName) {
+    return this.request("GET", `/v1/machines/${encodeURIComponent(idOrName)}`);
+  }
+  /** GET /v1/machines?metadata=k:v&...&limit=N. */
+  async listMachines(metadata, limit) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(metadata)) qs.append("metadata", `${k}:${v}`);
+    if (limit !== void 0) qs.set("limit", String(limit));
+    const suffix = qs.size > 0 ? `?${qs.toString()}` : "";
+    const raw = await this.request("GET", `/v1/machines${suffix}`);
+    if (Array.isArray(raw)) return raw;
+    const wrapped = raw;
+    if (Array.isArray(wrapped.machines)) return wrapped.machines;
+    return [];
+  }
+  /** GET /v1/usage (limits.maxMachines). */
+  readUsage() {
+    return this.request("GET", "/v1/usage");
+  }
+  /** PATCH /v1/machines/{id}. Answers 200 with the updated MACHINE (measured
+   *  live: `operationId` is null, there is no operation to wait on), so the
+   *  machine's own `id` must never be handed to `waitForOperation`. A pending
+   *  `operationId` is still awaited if the API ever returns one. */
+  async patchMachine(id, patch, idempotencyKey) {
+    const machine = await this.request("PATCH", `/v1/machines/${encodeURIComponent(id)}`, {
+      body: patch,
+      idempotency: idempotencyKey ?? crypto.randomUUID()
+    });
+    if (typeof machine.operationId === "string" && machine.operationId.length > 0) {
+      await this.waitForOperation(machine.operationId);
+    }
+    return machine;
+  }
+  /** DELETE /v1/machines/{id}. The API rejects a DELETE without an
+   *  `Idempotency-Key` (HTTP 400), so one is always sent. */
+  deleteMachine(id) {
+    return this.request("DELETE", `/v1/machines/${encodeURIComponent(id)}`, {
+      idempotency: crypto.randomUUID()
+    });
+  }
+  /** POST /v1/machines/{id}/ports {port}. 201 first, 200 if already published
+   *  (both answer the same body). */
+  async publishPort(id, port) {
+    return await this.request("POST", `/v1/machines/${encodeURIComponent(id)}/ports`, {
+      body: { port },
+      idempotency: crypto.randomUUID()
+    });
+  }
+  /** DELETE /v1/machines/{id}/ports/{port}. */
+  deletePort(id, port) {
+    return this.request("DELETE", `/v1/machines/${encodeURIComponent(id)}/ports/${port}`);
+  }
+  /** POST /v1/machines/{id}/{verb} for suspend|resume|stop|start. */
+  machineAction(id, verb) {
+    return this.request(
+      "POST",
+      `/v1/machines/${encodeURIComponent(id)}/${verb}`,
+      { idempotency: crypto.randomUUID() }
+    );
+  }
+  /** POST /v1/machines/{id}/wake: 200 DIRECT (no operation to wait on). */
+  wake(id) {
+    return this.request(
+      "POST",
+      `/v1/machines/${encodeURIComponent(id)}/wake`,
+      { idempotency: crypto.randomUUID() }
+    );
+  }
+  /** POST /v1/machines/{id}/exec. NEVER retried and NEVER idempotent: a
+   *  retry could double-run a mutating command. */
+  exec(id, input) {
+    return this.request(
+      "POST",
+      `/v1/machines/${encodeURIComponent(id)}/exec`,
+      { body: input, serviceTimeoutMs: EXEC_HTTP_TIMEOUT_MS }
+    );
+  }
+};
+function describeOperationError(op) {
+  const detail = op.error;
+  if (typeof detail === "string" && detail.length > 0) return `instabox: operation ${op.id} failed: ${detail}`;
+  if (detail !== null && typeof detail === "object") {
+    const code = asString(detail.code);
+    const message = asString(detail.message);
+    return `instabox: operation ${op.id} failed${code ? ` (${code})` : ""}${message ? `: ${message}` : ""}`;
+  }
+  return `instabox: operation ${op.id} failed.`;
+}
+function safeParse(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed !== null && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return {};
+}
+function isTransientInstaboxError(err) {
+  if (!(err instanceof InstaboxApiError)) {
+    return false;
+  }
+  return err.code === "transport_error" || err.status !== null && err.status >= 500;
+}
+function isTransportError(err) {
+  return err instanceof InstaboxApiError && err.code === "transport_error";
+}
+async function requestWithTransportRetry(fn, attempts) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= attempts || !isTransportError(err)) throw err;
+      await new Promise((resolve) => setTimeout(resolve, OPERATION_RETRY_BASE_DELAY_MS * attempt));
+    }
+  }
+}
+var DEFAULT_PORT = 18790;
+var DEFAULT_WORKSPACE = "/data/home";
+var DEFAULT_TEMPLATE = "universal";
+var DEFAULT_TIMEOUT_SECONDS = 3600;
+var MIN_TIMEOUT_SECONDS = 60;
+var MAX_TIMEOUT_SECONDS = 86400;
+var DEFAULT_AUTO_SUSPEND_AFTER_SECONDS = 0;
+var HEALTH_PROBE_TIMEOUT_MS = 5e3;
+var ALREADY_UP_PROBE_TIMEOUT_MS = 2e3;
+var POLL_INTERVAL_MS = 500;
+var READY_TIMEOUT_MS = 12e4;
+var DAEMON_READY_TIMEOUT_MS = 6e4;
+var EXEC_MAX_TIMEOUT_SECONDS = 600;
+var EXEC_DEFAULT_TIMEOUT_SECONDS = 600;
+var DEFAULT_UPDATE_CLI_TIMEOUT_SECONDS = 600;
+var FILE_CHUNK_BYTES = 700 * 1024;
+var FILE_CHUNK_B64_CHARS = Math.ceil(FILE_CHUNK_BYTES / 3) * 4;
+var AUTH_TOKEN_BYTES = 32;
+var PROVIDER_SLUG = "instabox";
+var ENV_FILE_DIR = "/etc/agentproto";
+var ENV_FILE_PATH = `${ENV_FILE_DIR}/agentproto.env`;
+var SYSTEMD_UNIT_PATH = "/etc/systemd/system/agentproto.service";
+var DAEMON_UNIT_NAME = "agentproto";
+var AUTH_TOKEN_ENV_VAR = "AGENTPROTO_AUTH_TOKEN";
+var AGENTPROTO_METADATA_KEY = "agentproto";
+var AGENTPROTO_METADATA_VALUE = "1";
+var BACKGROUND_REDIRECT = ">/dev/null 2>&1 </dev/null";
+function readConfig(rawConfig) {
+  const raw = rawConfig ?? {};
+  const num = (field, fallback, min, max) => {
+    if (typeof field !== "number" || !Number.isFinite(field)) return fallback;
+    return Math.min(max, Math.max(min, Math.floor(field)));
+  };
+  const str = (field) => typeof field === "string" && field.length > 0 ? field : void 0;
+  const metadata = typeof raw.metadata === "object" && raw.metadata !== null ? Object.fromEntries(
+    Object.entries(raw.metadata).filter(
+      (entry) => typeof entry[1] === "string"
+    )
+  ) : {};
+  return {
+    apiKey: str(raw.apiKey) ?? process.env.INSTABOX_API_KEY ?? "",
+    apiUrl: str(raw.apiUrl) ?? "https://api.instabox.sh",
+    template: str(raw.template) ?? DEFAULT_TEMPLATE,
+    timeoutSeconds: num(raw.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS, MAX_TIMEOUT_SECONDS),
+    autoSuspendAfterSeconds: typeof raw.autoSuspendAfterSeconds === "number" && Number.isFinite(raw.autoSuspendAfterSeconds) ? Math.min(86400, Math.max(0, Math.floor(raw.autoSuspendAfterSeconds))) : DEFAULT_AUTO_SUSPEND_AFTER_SECONDS,
+    port: num(raw.port, DEFAULT_PORT, 1, 65535),
+    workspace: str(raw.workspace) ?? DEFAULT_WORKSPACE,
+    cliVersion: str(raw.cliVersion) ?? "latest",
+    updateCliOnBoot: typeof raw.updateCliOnBoot === "boolean" ? raw.updateCliOnBoot : true,
+    installPackages: Array.isArray(raw.installPackages) ? raw.installPackages.filter((p) => typeof p === "string" && p.length > 0) : [],
+    updateCliTimeoutSeconds: num(
+      raw.updateCliTimeoutSeconds,
+      DEFAULT_UPDATE_CLI_TIMEOUT_SECONDS,
+      1,
+      EXEC_MAX_TIMEOUT_SECONDS
+    ),
+    readyTimeoutMs: num(raw.readyTimeoutMs, READY_TIMEOUT_MS, 1e3, 6e5),
+    daemonReadyTimeoutMs: num(raw.daemonReadyTimeoutMs, DAEMON_READY_TIMEOUT_MS, 1e3, 6e5),
+    metadata,
+    setupCommands: Array.isArray(raw.setupCommands) ? raw.setupCommands.filter((c) => typeof c === "string" && c.length > 0) : []
+  };
+}
+function environmentFileContents(env, authToken) {
+  const lines = [
+    ...Object.entries(env).map(([key, value]) => `${key}=${value}`),
+    `${AUTH_TOKEN_ENV_VAR}=${authToken}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function writeDaemonUnitCommand(port, workspace, env, authToken) {
+  const envFileContents = environmentFileContents(env, authToken);
+  const unit = [
+    "[Unit]",
+    "Description=agentproto daemon",
+    "After=network.target",
+    "",
+    "[Service]",
+    `EnvironmentFile=-${ENV_FILE_PATH}`,
+    `ExecStart=agentproto serve --port ${port} --bind 0.0.0.0 --workspace "${workspace}" --auth-token \${${AUTH_TOKEN_ENV_VAR}}`,
+    "Restart=always",
+    "User=user",
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target"
+  ].join("\n");
+  const command = [
+    "set -e",
+    `sudo mkdir -p ${ENV_FILE_DIR}`,
+    `sudo tee ${ENV_FILE_PATH} > /dev/null <<'AGENTPROTO_ENV'
+${envFileContents}AGENTPROTO_ENV`,
+    `sudo chmod 600 ${ENV_FILE_PATH}`,
+    `sudo tee ${SYSTEMD_UNIT_PATH} > /dev/null <<'AGENTPROTO_UNIT'
+${unit}
+AGENTPROTO_UNIT`
+  ].join("\n");
+  return { command, envFileContents, unitContents: unit };
+}
+function buildCliInstallCommand(cliVersion, extras) {
+  const extraText = extras.map((extra) => ` '${extra.replace(/'/g, "")}'`).join("");
+  return `sudo env "PATH=$PATH" npm i -g "@agentproto/cli@${cliVersion}"${extraText}`;
+}
+async function assertQuotaAvailable(client) {
+  const [usage, machines] = await Promise.all([
+    client.readUsage().catch(() => void 0),
+    client.listMachines({}, 200).catch(() => void 0)
+  ]);
+  const max = usage?.limits?.maxMachines;
+  if (typeof max === "number" && machines !== void 0 && machines.length >= max) {
+    throw new SandboxQuotaError(
+      PROVIDER_SLUG,
+      `instabox: account limit is ${max} machines and ${machines.length} already exist (suspended and stopped machines count); stop one before booting another.`
+    );
+  }
+}
+function normalizeQuotaError(err) {
+  if (err instanceof InstaboxApiError && isInstaboxQuotaFailure(err.status, err.code, err.message)) {
+    return new SandboxQuotaError(
+      PROVIDER_SLUG,
+      `instabox: account limit reached (HTTP ${err.status ?? "?"}, code "${err.code}"): fall back to a different sandbox provider.`,
+      err
+    );
+  }
+  return err;
+}
+function bootMetadata(config, spec) {
+  const sessionId = spec.id;
+  const metadata = { ...config.metadata };
+  metadata[AGENTPROTO_METADATA_KEY] = AGENTPROTO_METADATA_VALUE;
+  if (typeof sessionId === "string" && sessionId.length > 0) {
+    metadata.session = sessionId;
+  }
+  return metadata;
+}
+async function waitMachineReady(client, machineId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const machine = await client.getMachine(machineId);
+    if (machine.runtime?.ready === true) return machine;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `@agentproto/sandbox-instabox: machine ${machineId} did not reach runtime.ready within ${timeoutMs}ms.`
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+}
+async function probeHealth(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(HEALTH_PROBE_TIMEOUT_MS) });
+      if (res.ok) return true;
+    } catch {
+    }
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+}
+async function provisionAndProbe(state, deleteOnFailure) {
+  const { client, machineId, config } = state;
+  const published = await client.publishPort(machineId, config.port);
+  const publicUrl = published.url;
+  const healthUrl = `${publicUrl}/health`;
+  const alreadyUp = await probeHealth(healthUrl, ALREADY_UP_PROBE_TIMEOUT_MS);
+  if (!alreadyUp) {
+    if (config.updateCliOnBoot) {
+      await execChecked(client, machineId, "CLI install", {
+        cmd: buildCliInstallCommand(
+          config.cliVersion,
+          config.installPackages.map((extra) => extra.replace(/'/g, ""))
+        ),
+        timeoutSeconds: config.updateCliTimeoutSeconds
+      });
+    }
+    await execChecked(client, machineId, "workspace setup", {
+      cmd: `mkdir -p '${config.workspace}' && sudo mkdir -p ${ENV_FILE_DIR}`
+    });
+    await execChecked(
+      client,
+      machineId,
+      "daemon unit install",
+      { cmd: writeDaemonUnitCommand(config.port, config.workspace, state.env, state.authToken).command },
+      { quoteStderr: false }
+    );
+    for (const command of config.setupCommands) {
+      await execChecked(client, machineId, "setup command", {
+        cmd: command,
+        timeoutSeconds: EXEC_MAX_TIMEOUT_SECONDS
+      });
+    }
+    await execChecked(client, machineId, "daemon enable", {
+      cmd: `sudo systemctl daemon-reload && sudo systemctl enable --now ${DAEMON_UNIT_NAME} ${BACKGROUND_REDIRECT}`
+    });
+    const ready = await probeHealth(healthUrl, config.daemonReadyTimeoutMs);
+    if (!ready) {
+      if (deleteOnFailure) await client.deleteMachine(machineId).catch(() => void 0);
+      throw new Error(
+        `@agentproto/sandbox-instabox: agentproto daemon did not become healthy at ${healthUrl} within ${config.daemonReadyTimeoutMs}ms (machine ${machineId}).`
+      );
+    }
+  }
+  return { url: publicUrl, mcpUrl: `${publicUrl}/mcp` };
+}
+async function execScrubbed(client, machineId, input) {
+  try {
+    return await client.exec(machineId, input);
+  } catch (err) {
+    if (err instanceof Error) {
+      const scrubbed = scrubCommandFromMessage(err.message, input.cmd);
+      if (scrubbed !== err.message) {
+        const wrapped = new Error(scrubbed);
+        wrapped.name = err.name;
+        throw wrapped;
+      }
+    }
+    throw err;
+  }
+}
+async function execChecked(client, machineId, what, input, opts = {}) {
+  const result = await execScrubbed(client, machineId, input);
+  if (result.exitCode !== 0) {
+    const detail = opts.quoteStderr === false ? "" : scrubCommandFromMessage(result.stderr.trim(), input.cmd).slice(0, 300);
+    throw new Error(
+      `@agentproto/sandbox-instabox: ${what} failed on machine ${machineId} (exit ${result.exitCode}${result.timedOut ? ", timed out" : ""}${detail ? `: ${detail}` : ""}).`
+    );
+  }
+  return result;
+}
+function newInstanceName() {
+  return `agentproto-${randomBytes(5).toString("hex")}`;
+}
+function newAuthToken() {
+  return randomBytes(AUTH_TOKEN_BYTES).toString("hex");
+}
+function machineIdOf(machine) {
+  if (typeof machine.id !== "string" || machine.id.length === 0) {
+    throw new Error("instabox: machine response carries no id");
+  }
+  return machine.id;
+}
+function clampTimeoutSeconds(seconds) {
+  return Math.min(MAX_TIMEOUT_SECONDS, Math.max(MIN_TIMEOUT_SECONDS, Math.floor(seconds)));
+}
+function clampExecTimeoutSeconds(timeoutMs) {
+  const seconds = Math.floor((timeoutMs ?? EXEC_DEFAULT_TIMEOUT_SECONDS * 1e3) / 1e3);
+  return Math.min(EXEC_MAX_TIMEOUT_SECONDS, Math.max(1, seconds));
+}
+function toBootedSandbox(client, machineId, mcpUrl, authToken, config, ports) {
+  return {
+    mcpUrl,
+    sandboxId: machineId,
+    ...Object.keys(ports).length > 0 ? { ports } : {},
+    // The public edge is UNGATED at InstaBox: the daemon's own bearer (minted
+    // here at unit install time and substituted from the 0600 EnvironmentFile)
+    // is the only thing gating /mcp, so it is ALWAYS surfaced.
+    token: authToken,
+    authHeaders: { Authorization: `Bearer ${authToken}` },
+    async stop() {
+      try {
+        const op = await client.deleteMachine(machineId);
+        await client.waitForOperation(op.id);
+      } catch (err) {
+        if (err instanceof InstaboxApiError && err.status === 404) return;
+        await client.deleteMachine(machineId).catch(() => void 0);
+        throw err;
+      }
+    },
+    async exec(opts) {
+      const startedAt = Date.now();
+      const result = await client.exec(machineId, {
+        cmd: opts.command,
+        ...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
+        ...opts.env !== void 0 ? { envs: opts.env } : {},
+        // InstaBox clamps exec 1..600s. An omitted bound maps to the max,
+        // NOT the API's own 60s default (mid-work-kill trap, module docs).
+        timeoutSeconds: clampExecTimeoutSeconds(opts.timeoutMs)
+      });
+      return {
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        durationMs: Date.now() - startedAt,
+        ...result.truncated ? { truncated: result.truncated } : {}
+      };
+    },
+    async readFile(path) {
+      const chunks = [];
+      for (let index = 0; ; index++) {
+        const result = await client.exec(machineId, {
+          cmd: `test -r '${path}' && dd if='${path}' ibs=${FILE_CHUNK_BYTES} skip=${index} count=1 2>/dev/null | base64 -w0`,
+          timeoutSeconds: EXEC_MAX_TIMEOUT_SECONDS
+        });
+        const encoded = result.stdout.trim();
+        if (index === 0 && result.exitCode !== 0 && encoded === "") {
+          throw new Error(
+            `instabox readFile: cannot read "${path}" (exit ${result.exitCode}, stderr: ${result.stderr.trim() || "(none)"})`
+          );
+        }
+        if (encoded.length === 0) break;
+        chunks.push(new Uint8Array(Buffer.from(encoded, "base64")));
+        if (encoded.length < FILE_CHUNK_B64_CHARS) break;
+      }
+      const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+      const out = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return out;
+    },
+    async writeFile(path, data) {
+      const encoded = Buffer.from(data).toString("base64");
+      const directory = path.slice(0, Math.max(path.lastIndexOf("/"), 0)) || "/";
+      for (let offset = 0, index = 0; index === 0 || offset < encoded.length; offset += FILE_CHUNK_B64_CHARS, index++) {
+        const slice = encoded.slice(offset, offset + FILE_CHUNK_B64_CHARS);
+        await client.exec(machineId, {
+          cmd: index === 0 ? `mkdir -p '${directory}' && base64 -d > '${path}'` : `base64 -d >> '${path}'`,
+          stdin: slice,
+          timeoutSeconds: EXEC_MAX_TIMEOUT_SECONDS
+        });
+      }
+    },
+    async expose(port) {
+      const published = await client.publishPort(machineId, port);
+      return { url: published.url };
+    },
+    async extendTimeout(ms) {
+      const seconds = clampTimeoutSeconds(ms / 1e3);
+      await client.patchMachine(machineId, { timeoutSeconds: seconds });
+    },
+    lifetimeMs: config.timeoutSeconds * 1e3
+  };
+}
+async function reviveMachine(client, machineId, state) {
+  if (state === "running") return;
+  if (state === "suspended") {
+    try {
+      await client.wake(machineId);
+      return;
+    } catch (err) {
+      const conflict = err instanceof InstaboxApiError && (err.status === 409 || err.code === "machine_not_running");
+      if (!conflict) throw err;
+    }
+    const resume = await client.machineAction(machineId, "resume").catch((err) => {
+      throw new Error(
+        `@agentproto/sandbox-instabox: machine ${machineId} is suspended and refused both wake and resume (${err instanceof Error ? err.message : String(err)}).`
+      );
+    });
+    await client.waitForOperation(resume.id);
+    return;
+  }
+  const start = await client.machineAction(machineId, "start").catch((err) => {
+    throw new Error(
+      `@agentproto/sandbox-instabox: machine ${machineId} is "${state}" and refused start (${err instanceof Error ? err.message : String(err)}).`
+    );
+  });
+  await client.waitForOperation(start.id);
+}
+async function readExistingAuthToken(client, machineId) {
+  const result = await client.exec(machineId, {
+    cmd: `sudo grep '^${AUTH_TOKEN_ENV_VAR}=' ${ENV_FILE_PATH} 2>/dev/null || true`,
+    timeoutSeconds: 60
+  });
+  const line = result.stdout.split("\n").map((entry) => entry.trim()).find((entry) => entry.startsWith(`${AUTH_TOKEN_ENV_VAR}=`));
+  const value = line?.slice(`${AUTH_TOKEN_ENV_VAR}=`.length);
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`instabox: ${AUTH_TOKEN_ENV_VAR} missing from the daemon env file`);
+  }
+  return value;
+}
+function resolveExtraPorts(spec) {
+  const extras = spec.extraPorts;
+  if (!Array.isArray(extras)) return [];
+  return extras.filter((port) => typeof port === "number" && Number.isInteger(port));
+}
+function createInstaboxSandboxProvider(baseConfig = {}) {
+  function resolveConfig(spec) {
+    const raw = spec.config ?? {};
+    const merged = { ...baseConfig, ...raw };
+    if (baseConfig.metadata !== void 0 && raw.metadata !== void 0) {
+      merged.metadata = {
+        ...baseConfig.metadata,
+        ...typeof raw.metadata === "object" && raw.metadata !== null ? raw.metadata : {}
+      };
+    }
+    return readConfig(merged);
+  }
+  function assertApiKey(config) {
+    if (config.apiKey === "") {
+      throw new Error(
+        "@agentproto/sandbox-instabox: no InstaBox API key \u2014 set spec.config.apiKey or the INSTABOX_API_KEY environment variable."
+      );
+    }
+  }
+  return {
+    async boot(spec, opts) {
+      const config = resolveConfig(spec);
+      assertApiKey(config);
+      const client = new InstaboxClient({ apiKey: config.apiKey, apiUrl: config.apiUrl });
+      const authToken = newAuthToken();
+      await assertQuotaAvailable(client);
+      const created = await client.createMachine(
+        {
+          name: newInstanceName(),
+          templateId: config.template,
+          timeoutSeconds: config.timeoutSeconds,
+          onTimeout: "kill",
+          autoSuspendAfterSeconds: config.autoSuspendAfterSeconds,
+          metadata: bootMetadata(config, spec),
+          // ALWAYS sent and ALWAYS false: a vault would write the caller's
+          // secrets into a box that runs agent code.
+          vault: false
+        },
+        crypto.randomUUID()
+      ).catch((err) => {
+        throw normalizeQuotaError(err);
+      });
+      try {
+        await client.waitForOperation(created.id);
+        const machineId = created.machineId ?? created.machine?.id;
+        if (machineId === void 0) {
+          throw new Error(
+            `@agentproto/sandbox-instabox: create operation ${created.id} settled with no machine id.`
+          );
+        }
+        await waitMachineReady(client, machineId, config.readyTimeoutMs);
+        const extraPorts = resolveExtraPorts(spec);
+        const provisioned = await provisionAndProbe(
+          { client, machineId, config, env: opts.env, authToken },
+          true
+        );
+        const ports = {};
+        for (const port of extraPorts) {
+          ports[port] = (await client.publishPort(machineId, port)).url;
+        }
+        return toBootedSandbox(client, machineId, provisioned.mcpUrl, authToken, config, ports);
+      } catch (err) {
+        const machineId = created.machineId ?? created.machine?.id;
+        if (machineId !== void 0) await client.deleteMachine(machineId).catch(() => void 0);
+        throw normalizeQuotaError(err);
+      }
+    },
+    /** Reconnect to an existing box, state-aware (see `reviveMachine`).
+     *  State mapping: `running` = ok, auto-`suspended` = `wake`, manually
+     *  `suspended` or `stopped` = `resume`/`start` as the API allows, else a
+     *  clear error. A deleted machine surfaces as `SandboxBoxGoneError`. */
+    async connect(sandboxId, spec, opts) {
+      const config = resolveConfig(spec);
+      assertApiKey(config);
+      const client = new InstaboxClient({ apiKey: config.apiKey, apiUrl: config.apiUrl });
+      let machine;
+      try {
+        machine = await client.getMachine(sandboxId);
+      } catch (err) {
+        if (err instanceof InstaboxApiError && err.status === 404) {
+          throw new SandboxBoxGoneError(sandboxId, err);
+        }
+        throw err;
+      }
+      const machineId = machineIdOf(machine);
+      await reviveMachine(client, machineId, machine.state);
+      await waitMachineReady(client, machineId, config.readyTimeoutMs);
+      if (machine.state !== "running" && (await client.getMachine(machineId)).state !== "running") {
+        throw new Error(
+          `@agentproto/sandbox-instabox: machine ${machineId} did not reach "running" \u2014 cannot reconnect.`
+        );
+      }
+      let authToken;
+      try {
+        authToken = await readExistingAuthToken(client, machineId);
+      } catch (err) {
+        throw new Error(
+          `@agentproto/sandbox-instabox: machine ${machineId} is running but its daemon token could not be read from ${ENV_FILE_PATH} (${err instanceof Error ? err.message : String(err)}) \u2014 reconnect needs the token the boot that installed the daemon issued.`
+        );
+      }
+      await client.patchMachine(machineId, { timeoutSeconds: clampTimeoutSeconds(config.timeoutSeconds) });
+      const provisioned = await provisionAndProbe(
+        { client, machineId, config, env: opts.env, authToken },
+        false
+      );
+      const ports = {};
+      for (const port of resolveExtraPorts(spec)) {
+        ports[port] = (await client.publishPort(machineId, port)).url;
+      }
+      return toBootedSandbox(client, machineId, provisioned.mcpUrl, authToken, config, ports);
+    },
+    /** Provider control-plane liveness: 404 means gone; any other answer (or
+     *  thrown error) stays verbatim so callers read "check failed", never
+     *  "box died". */
+    async probe(sandboxId) {
+      const providerApiKey = baseConfig.apiKey ?? process.env.INSTABOX_API_KEY;
+      if (providerApiKey === void 0 || providerApiKey === "") {
+        throw new Error(
+          "@agentproto/sandbox-instabox: no InstaBox API key for probe \u2014 construct the provider with createInstaboxSandboxProvider({ apiKey }) or set INSTABOX_API_KEY."
+        );
+      }
+      const client = new InstaboxClient({ apiKey: providerApiKey, apiUrl: baseConfig.apiUrl });
+      try {
+        const machine = await client.getMachine(sandboxId);
+        return { alive: true, ...machine.state !== void 0 ? { state: String(machine.state) } : {} };
+      } catch (err) {
+        if (err instanceof InstaboxApiError && err.status === 404) return { alive: false };
+        throw err;
+      }
+    }
+  };
+}
+var instaboxSandboxProvider = createInstaboxSandboxProvider();
+
+export { AGENTPROTO_METADATA_KEY, AUTH_TOKEN_ENV_VAR, BACKGROUND_REDIRECT, DAEMON_UNIT_NAME, ENV_FILE_PATH, InstaboxApiError, InstaboxClient, SYSTEMD_UNIT_PATH, assertQuotaAvailable, buildCliInstallCommand, createInstaboxSandboxProvider, environmentFileContents, instaboxSandboxProvider, isInstaboxQuotaFailure, isTransientInstaboxError, normalizeQuotaError, writeDaemonUnitCommand };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map