@coder/ai-sdk-sandbox 0.1.0

package/dist/index.js

@@ -0,0 +1,982 @@
+// src/cli-transport.ts
+import { spawn as nodeSpawn } from "child_process";
+import net from "net";
+import { Readable } from "stream";
+
+// src/shell.ts
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildRemoteScript(options) {
+  const segments = [];
+  if (options.workingDirectory !== void 0 && options.workingDirectory !== "") {
+    segments.push(`cd ${shellQuote(options.workingDirectory)} &&`);
+  }
+  const envEntries = Object.entries(options.env ?? {});
+  if (envEntries.length > 0) {
+    const assignments = envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
+    segments.push(`env ${assignments} bash -c ${shellQuote(options.command)}`);
+  } else {
+    segments.push(options.command);
+  }
+  return segments.join(" ");
+}
+
+// src/cli-transport.ts
+var DEFAULT_PORT_FORWARD_TIMEOUT_MS = 3e4;
+function buildSshArgs(workspace, remoteScript, options) {
+  const shell = options.loginShell ? "bash -lc" : "bash -c";
+  const remoteCommand = `${shell} ${shellQuote(remoteScript)}`;
+  const proxy = `${shellQuote(options.coderBinary)} ssh --stdio --wait=${options.waitMode} ${shellQuote(workspace)}` + (options.silenceProxyStderr ? " 2>/dev/null" : "");
+  return [
+    "-o",
+    `ProxyCommand=${proxy}`,
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-o",
+    "UserKnownHostsFile=/dev/null",
+    "-o",
+    "LogLevel=ERROR",
+    "-T",
+    sshHostAlias(workspace),
+    remoteCommand
+  ];
+}
+function sshHostAlias(workspace) {
+  return `coder.${workspace.replace(/[^A-Za-z0-9_.-]/g, "-")}`;
+}
+function buildLocalForwardArgs(workspace, localPort, remotePort, options) {
+  const proxy = `${shellQuote(options.coderBinary)} ssh --stdio --wait=${options.waitMode} ${shellQuote(workspace)}` + (options.silenceProxyStderr ? " 2>/dev/null" : "");
+  return [
+    "-o",
+    `ProxyCommand=${proxy}`,
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-o",
+    "UserKnownHostsFile=/dev/null",
+    "-o",
+    "LogLevel=ERROR",
+    "-o",
+    "ExitOnForwardFailure=yes",
+    "-N",
+    "-L",
+    `${localPort}:127.0.0.1:${remotePort}`,
+    sshHostAlias(workspace)
+  ];
+}
+function buildCreateArgs(options) {
+  const args = ["create", options.workspace, "--yes", "--template", options.template];
+  if (options.templateVersion !== void 0) {
+    args.push("--template-version", options.templateVersion);
+  }
+  if (options.preset !== void 0) {
+    args.push("--preset", options.preset);
+  }
+  for (const [name, value] of Object.entries(options.parameters ?? {})) {
+    args.push("--parameter", `${name}=${value}`);
+  }
+  if (options.parameterFile !== void 0) {
+    args.push("--rich-parameter-file", options.parameterFile);
+  }
+  if (options.useParameterDefaults) {
+    args.push("--use-parameter-defaults");
+  }
+  for (const [name, value] of Object.entries(options.ephemeralParameters ?? {})) {
+    args.push("--ephemeral-parameter", `${name}=${value}`);
+  }
+  if (options.stopAfter !== void 0) {
+    args.push("--stop-after", options.stopAfter);
+  }
+  if (options.automaticUpdates !== void 0) {
+    args.push("--automatic-updates", options.automaticUpdates);
+  }
+  if (options.org !== void 0) {
+    args.push("--org", options.org);
+  }
+  return args;
+}
+function parseWorkspaceRef(ref) {
+  const slashCount = (ref.match(/\//g) ?? []).length;
+  if (slashCount > 1) {
+    throw new Error(`invalid workspace reference "${ref}"; expected [owner/]name[.agent]`);
+  }
+  const [ownerOrName, maybeName] = ref.includes("/") ? ref.split("/", 2) : ["me", ref];
+  const name = (maybeName ?? ownerOrName).split(".")[0] ?? "";
+  if (name === "" || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) {
+    throw new Error(`invalid workspace reference "${ref}"; expected [owner/]name[.agent]`);
+  }
+  return { owner: ownerOrName === "" ? "me" : ownerOrName, name };
+}
+function parseWorkspaceStatus(workspace) {
+  const ws = asRecord(workspace);
+  const build = asRecord(ws.latest_build);
+  const resources = Array.isArray(build.resources) ? build.resources : [];
+  const agents = [];
+  for (const resource of resources) {
+    const list = asRecord(resource).agents;
+    if (!Array.isArray(list)) continue;
+    for (const agent of list) {
+      const a = asRecord(agent);
+      agents.push({
+        name: typeof a.name === "string" ? a.name : "",
+        status: typeof a.status === "string" ? a.status : "connecting",
+        lifecycleState: typeof a.lifecycle_state === "string" ? a.lifecycle_state : "created"
+      });
+    }
+  }
+  return {
+    name: typeof ws.name === "string" ? ws.name : "",
+    buildStatus: typeof build.status === "string" ? build.status : "pending",
+    transition: typeof build.transition === "string" ? build.transition : "start",
+    agents
+  };
+}
+function parsePresetsOutput(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed === "" || /^no presets found/i.test(trimmed)) return [];
+  return parsePresetList(JSON.parse(trimmed));
+}
+function parsePresetList(json) {
+  if (!Array.isArray(json)) return [];
+  return json.map((entry) => {
+    const record = asRecord(entry);
+    const preset = asRecord(record.TemplatePreset ?? record);
+    const name = pickString(preset, "Name", "name") ?? "";
+    const description = pickString(preset, "Description", "description");
+    return {
+      name,
+      default: pickBoolean(preset, "Default", "default") ?? false,
+      ...description !== void 0 && description !== "" ? { description } : {}
+    };
+  });
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+function pickString(record, ...keys) {
+  for (const key of keys) {
+    if (typeof record[key] === "string") return record[key];
+  }
+  return void 0;
+}
+function pickBoolean(record, ...keys) {
+  for (const key of keys) {
+    if (typeof record[key] === "boolean") return record[key];
+  }
+  return void 0;
+}
+var CoderCliTransport = class {
+  #coderBinary;
+  #sshBinary;
+  #url;
+  #token;
+  #extraEnv;
+  #loginShell;
+  #waitMode;
+  #silenceProxyStderr;
+  #portForwardTimeoutMs;
+  constructor(options = {}) {
+    this.#coderBinary = options.coderBinary ?? "coder";
+    this.#sshBinary = options.sshBinary ?? "ssh";
+    this.#url = options.url;
+    this.#token = options.token;
+    this.#extraEnv = options.env ?? {};
+    this.#loginShell = options.loginShell ?? true;
+    this.#waitMode = options.waitMode ?? "no";
+    this.#silenceProxyStderr = options.silenceProxyStderr ?? true;
+    this.#portForwardTimeoutMs = options.portForwardTimeoutMs ?? DEFAULT_PORT_FORWARD_TIMEOUT_MS;
+  }
+  #childEnv() {
+    return {
+      ...process.env,
+      ...this.#url ? { CODER_URL: this.#url } : {},
+      ...this.#token ? { CODER_SESSION_TOKEN: this.#token } : {},
+      ...this.#extraEnv
+    };
+  }
+  #sshArgs(options) {
+    const script = buildRemoteScript({
+      command: options.command,
+      workingDirectory: options.workingDirectory,
+      env: options.env
+    });
+    return buildSshArgs(options.workspace, script, {
+      coderBinary: this.#coderBinary,
+      loginShell: this.#loginShell,
+      waitMode: this.#waitMode,
+      silenceProxyStderr: this.#silenceProxyStderr
+    });
+  }
+  exec(options) {
+    return this.#run(this.#sshBinary, this.#sshArgs(options), {
+      stdin: options.stdin,
+      abortSignal: options.abortSignal
+    });
+  }
+  spawn(options) {
+    const child = nodeSpawn(this.#sshBinary, this.#sshArgs(options), {
+      stdio: [options.stdin !== void 0 ? "pipe" : "ignore", "pipe", "pipe"],
+      env: this.#childEnv(),
+      signal: options.abortSignal
+    });
+    writeStdin(child, options.stdin);
+    return toSpawnedProcess(child, this.#sshBinary, options.abortSignal);
+  }
+  async forwardPort(options) {
+    const localPort = await allocateLocalPort();
+    const child = nodeSpawn(
+      this.#sshBinary,
+      buildLocalForwardArgs(options.workspace, localPort, options.remotePort, {
+        coderBinary: this.#coderBinary,
+        waitMode: this.#waitMode,
+        silenceProxyStderr: this.#silenceProxyStderr
+      }),
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: this.#childEnv(),
+        signal: options.abortSignal
+      }
+    );
+    let closed = false;
+    child.once("close", () => {
+      closed = true;
+    });
+    child.once("error", () => {
+      closed = true;
+    });
+    let stderr = "";
+    child.stderr?.setEncoding("utf8");
+    const onStderr = (chunk) => {
+      stderr += chunk;
+    };
+    child.stderr?.on("data", onStderr);
+    try {
+      await waitForLocalPort(localPort, child, this.#portForwardTimeoutMs, options.abortSignal);
+    } catch (error) {
+      child.kill("SIGTERM");
+      const code = error?.code;
+      if (code === "ENOENT" || code === "EACCES") {
+        throw describeSpawnError(error, this.#sshBinary);
+      }
+      const detail = stderr.trim();
+      throw new Error(
+        `ssh -L forward (${options.workspace} :${options.remotePort}) failed to become ready` + (detail ? `: ${detail}` : ""),
+        { cause: error }
+      );
+    }
+    child.stderr?.off("data", onStderr);
+    return {
+      localHost: "127.0.0.1",
+      localPort,
+      get closed() {
+        return closed;
+      },
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        child.kill("SIGTERM");
+      }
+    };
+  }
+  async start(workspace, options) {
+    await this.#runLifecycle(["start", workspace, "--yes"], workspace, "start", options);
+  }
+  async stop(workspace, options) {
+    await this.#runLifecycle(["stop", workspace, "--yes"], workspace, "stop", options);
+  }
+  async destroy(workspace, options) {
+    await this.#runLifecycle(["delete", workspace, "--yes"], workspace, "delete", options);
+  }
+  async status(workspace, options) {
+    const { owner, name } = parseWorkspaceRef(workspace);
+    const result = await this.#run(
+      this.#coderBinary,
+      ["list", "--output", "json", "--search", `owner:${owner} name:${name}`],
+      { abortSignal: options?.abortSignal }
+    );
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `coder list (${workspace}) failed (exit ${result.exitCode}): ${(result.stderr || result.stdout).trim()}`
+      );
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch (error) {
+      throw new Error(`coder list (${workspace}) returned invalid JSON`, { cause: error });
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) return null;
+    return parseWorkspaceStatus(parsed[0]);
+  }
+  async create(options) {
+    const result = await this.#run(this.#coderBinary, buildCreateArgs(options), {
+      abortSignal: options.abortSignal
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `coder create ${options.workspace} (template ${options.template}) failed (exit ${result.exitCode}): ${(result.stderr || result.stdout).trim()}`
+      );
+    }
+  }
+  async listPresets(options) {
+    const args = ["templates", "presets", "list", options.template, "--output", "json"];
+    if (options.templateVersion !== void 0) {
+      args.push("--template-version", options.templateVersion);
+    }
+    if (options.org !== void 0) {
+      args.push("--org", options.org);
+    }
+    const result = await this.#run(this.#coderBinary, args, {
+      abortSignal: options.abortSignal
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `coder templates presets list ${options.template} failed (exit ${result.exitCode}): ${(result.stderr || result.stdout).trim()}`
+      );
+    }
+    try {
+      return parsePresetsOutput(result.stdout);
+    } catch (error) {
+      throw new Error(
+        `coder templates presets list ${options.template} returned invalid JSON: ` + result.stdout.trim().slice(0, 120),
+        { cause: error }
+      );
+    }
+  }
+  async #runLifecycle(args, workspace, verb, options) {
+    const result = await this.#run(this.#coderBinary, args, {
+      abortSignal: options?.abortSignal
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `coder ${verb} ${workspace} failed (exit ${result.exitCode}): ${(result.stderr || result.stdout).trim()}`
+      );
+    }
+  }
+  #run(binary, args, options) {
+    return new Promise((resolve, reject) => {
+      const child = nodeSpawn(binary, args, {
+        stdio: [options.stdin !== void 0 ? "pipe" : "ignore", "pipe", "pipe"],
+        env: this.#childEnv(),
+        signal: options.abortSignal
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk;
+      });
+      child.on("error", (error) => reject(describeSpawnError(error, binary)));
+      child.on("close", (code) => {
+        resolve({ exitCode: code ?? 0, stdout, stderr });
+      });
+      writeStdin(child, options.stdin);
+    });
+  }
+};
+function describeSpawnError(error, binary) {
+  const code = error?.code;
+  if (code === "ENOENT" || code === "EACCES") {
+    return new Error(
+      `failed to launch "${binary}": ${code === "ENOENT" ? "not found on PATH" : "not executable"}. Install the Coder CLI (https://coder.com/docs/install) and run \`coder login\`, ensure an OpenSSH client is on PATH, or set explicit paths via new CoderCliTransport({ coderBinary, sshBinary }).`,
+      { cause: error }
+    );
+  }
+  return error;
+}
+function writeStdin(child, stdin) {
+  if (stdin === void 0 || child.stdin === null) return;
+  child.stdin.on("error", () => {
+  });
+  child.stdin.end(stdin);
+}
+function toSpawnedProcess(child, binary, abortSignal) {
+  const stdout = nodeReadableToWebStream(child.stdout);
+  const stderr = nodeReadableToWebStream(child.stderr);
+  let settled = false;
+  const wait = new Promise((resolve, reject) => {
+    const onError = (error) => finish(() => reject(describeSpawnError(error, binary)));
+    const onClose = (code) => finish(() => resolve({ exitCode: code ?? 0 }));
+    const onAbort = () => finish(() => reject(abortSignal?.reason ?? new Error("aborted")));
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      child.off("error", onError);
+      child.off("close", onClose);
+      abortSignal?.removeEventListener("abort", onAbort);
+      fn();
+    };
+    child.on("error", onError);
+    child.on("close", onClose);
+    if (abortSignal) {
+      if (abortSignal.aborted) {
+        finish(() => reject(abortSignal.reason ?? new Error("aborted")));
+      } else {
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+  });
+  return {
+    pid: child.pid,
+    stdout,
+    stderr,
+    wait: () => wait,
+    kill: async () => {
+      child.kill("SIGTERM");
+    }
+  };
+}
+function nodeReadableToWebStream(readable) {
+  if (readable === null) {
+    return new ReadableStream({
+      start(controller) {
+        controller.close();
+      }
+    });
+  }
+  return Readable.toWeb(readable);
+}
+function allocateLocalPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      server.close(() => {
+        if (port === 0) reject(new Error("failed to allocate a local port"));
+        else resolve(port);
+      });
+    });
+  });
+}
+function waitForLocalPort(port, child, timeoutMs, abortSignal) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const settle = (fn) => {
+      if (done) return;
+      done = true;
+      child.off("close", onClose);
+      child.off("error", onError);
+      abortSignal?.removeEventListener("abort", onAbort);
+      fn();
+    };
+    const onClose = (code) => settle(() => reject(new Error(`ssh -L forward exited early (code ${code ?? "null"})`)));
+    const onError = (error) => settle(() => reject(error));
+    const onAbort = () => settle(() => reject(abortSignal?.reason ?? new Error("aborted")));
+    child.on("close", onClose);
+    child.on("error", onError);
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+    const attempt = () => {
+      if (done) return;
+      const socket = net.connect(port, "127.0.0.1");
+      socket.once("connect", () => {
+        socket.destroy();
+        settle(resolve);
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        if (done) return;
+        if (Date.now() > deadline) {
+          settle(() => reject(new Error(`timed out waiting for local port ${port}`)));
+          return;
+        }
+        setTimeout(attempt, 200);
+      });
+    };
+    attempt();
+  });
+}
+
+// src/coder-workspace-provider.ts
+import { createHash } from "crypto";
+import { setTimeout as delay } from "timers/promises";
+
+// src/file-io.ts
+import path from "path";
+var MISSING_FILE_EXIT = 66;
+function resolveRemotePath(ctx, p) {
+  return p.startsWith("/") ? p : path.posix.join(ctx.defaultWorkingDirectory, p);
+}
+async function readBinaryFile(ctx, options) {
+  const abs = resolveRemotePath(ctx, options.path);
+  const quoted = shellQuote(abs);
+  const command = `if [ -f ${quoted} ]; then base64 < ${quoted}; else exit ${MISSING_FILE_EXIT}; fi`;
+  const result = await ctx.transport.exec({
+    workspace: ctx.workspace,
+    command,
+    abortSignal: options.abortSignal
+  });
+  if (result.exitCode === MISSING_FILE_EXIT) return null;
+  if (result.exitCode !== 0) {
+    throw new Error(`failed to read ${abs} (exit ${result.exitCode}): ${result.stderr.trim()}`);
+  }
+  const base64 = result.stdout.replace(/\s+/g, "");
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+async function readFile(ctx, options) {
+  const bytes = await readBinaryFile(ctx, options);
+  if (bytes === null) return null;
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    }
+  });
+}
+async function readTextFile(ctx, options) {
+  const bytes = await readBinaryFile(ctx, {
+    path: options.path,
+    abortSignal: options.abortSignal
+  });
+  if (bytes === null) return null;
+  const text = Buffer.from(bytes).toString(normalizeEncoding(options.encoding));
+  if (options.startLine === void 0 && options.endLine === void 0) {
+    return text;
+  }
+  return sliceLines(text, options.startLine, options.endLine);
+}
+async function writeBinaryFile(ctx, options) {
+  const abs = resolveRemotePath(ctx, options.path);
+  const dir = path.posix.dirname(abs);
+  const command = `mkdir -p ${shellQuote(dir)} && base64 -d > ${shellQuote(abs)}`;
+  const base64 = Buffer.from(options.content).toString("base64");
+  const result = await ctx.transport.exec({
+    workspace: ctx.workspace,
+    command,
+    stdin: base64,
+    abortSignal: options.abortSignal
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`failed to write ${abs} (exit ${result.exitCode}): ${result.stderr.trim()}`);
+  }
+}
+async function writeFile(ctx, options) {
+  const bytes = await collectStream(options.content);
+  await writeBinaryFile(ctx, {
+    path: options.path,
+    content: bytes,
+    abortSignal: options.abortSignal
+  });
+}
+async function writeTextFile(ctx, options) {
+  const bytes = new Uint8Array(Buffer.from(options.content, normalizeEncoding(options.encoding)));
+  await writeBinaryFile(ctx, {
+    path: options.path,
+    content: bytes,
+    abortSignal: options.abortSignal
+  });
+}
+function sliceLines(text, startLine, endLine) {
+  const lines = text.split("\n");
+  const start = Math.max(1, startLine ?? 1) - 1;
+  const end = endLine === void 0 ? lines.length : Math.min(lines.length, endLine);
+  return lines.slice(start, end).join("\n");
+}
+function normalizeEncoding(encoding) {
+  if (encoding === void 0) return "utf8";
+  const normalized = encoding.toLowerCase().replace(/[-_]/g, "");
+  switch (normalized) {
+    case "utf8":
+    case "utf":
+      return "utf8";
+    case "utf16le":
+    case "ucs2":
+      return "utf16le";
+    case "latin1":
+    case "binary":
+    case "iso88591":
+      return "latin1";
+    case "ascii":
+      return "ascii";
+    case "base64":
+      return "base64";
+    case "hex":
+      return "hex";
+    default:
+      return "utf8";
+  }
+}
+async function collectStream(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        chunks.push(value);
+        total += value.length;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+// src/coder-workspace-session.ts
+var CoderWorkspaceSession = class {
+  id;
+  defaultWorkingDirectory;
+  description;
+  #transport;
+  #workspace;
+  #ownsLifecycle;
+  #forwards = /* @__PURE__ */ new Map();
+  #ports;
+  #stopped = false;
+  constructor(config) {
+    this.#transport = config.transport;
+    this.#workspace = config.workspace;
+    this.#ownsLifecycle = config.ownsLifecycle;
+    this.#ports = [...config.ports];
+    this.id = config.id;
+    this.defaultWorkingDirectory = config.defaultWorkingDirectory;
+    this.description = `Coder workspace "${config.workspace}". Default working directory: ${config.defaultWorkingDirectory}. Exposed ports: ${this.#ports.length > 0 ? this.#ports.join(", ") : "none"}. Commands run inside the workspace via 'coder ssh'.`;
+  }
+  get ports() {
+    return this.#ports;
+  }
+  #execOptions(options) {
+    return {
+      workspace: this.#workspace,
+      command: options.command,
+      workingDirectory: options.workingDirectory ?? this.defaultWorkingDirectory,
+      env: options.env,
+      abortSignal: options.abortSignal
+    };
+  }
+  #fileIoContext() {
+    return {
+      transport: this.#transport,
+      workspace: this.#workspace,
+      defaultWorkingDirectory: this.defaultWorkingDirectory
+    };
+  }
+  // --- exec surface ---------------------------------------------------------
+  run = (options) => this.#transport.exec(this.#execOptions(options));
+  spawn = async (options) => this.#transport.spawn(this.#execOptions(options));
+  // --- file I/O surface -----------------------------------------------------
+  readFile = (options) => readFile(this.#fileIoContext(), options);
+  readBinaryFile = (options) => readBinaryFile(this.#fileIoContext(), options);
+  readTextFile = (options) => readTextFile(this.#fileIoContext(), options);
+  writeFile = (options) => writeFile(this.#fileIoContext(), options);
+  writeBinaryFile = (options) => writeBinaryFile(this.#fileIoContext(), options);
+  writeTextFile = (options) => writeTextFile(this.#fileIoContext(), options);
+  // --- network surface ------------------------------------------------------
+  getPortUrl = async (options) => {
+    if (this.#stopped) {
+      throw new Error("cannot resolve a port URL: the sandbox session is stopped");
+    }
+    let forward = this.#forwards.get(options.port);
+    if (forward !== void 0) {
+      const existing = await forward.catch(() => void 0);
+      if (existing === void 0 || existing.closed) {
+        this.#forwards.delete(options.port);
+        if (existing?.closed) void existing.close().catch(() => {
+        });
+        forward = void 0;
+      }
+    }
+    if (forward === void 0) {
+      forward = this.#transport.forwardPort({
+        workspace: this.#workspace,
+        remotePort: options.port
+      });
+      this.#forwards.set(options.port, forward);
+      forward.catch(() => this.#forwards.delete(options.port));
+    }
+    const resolved = await forward;
+    const scheme = localScheme(options.protocol ?? "ws");
+    return `${scheme}://${resolved.localHost}:${resolved.localPort}`;
+  };
+  setPorts = async (ports, _options) => {
+    const next = [...ports];
+    for (const [port, forward] of this.#forwards) {
+      if (!next.includes(port)) {
+        this.#forwards.delete(port);
+        void forward.then((f) => f.close()).catch(() => {
+        });
+      }
+    }
+    this.#ports = next;
+  };
+  // --- lifecycle ------------------------------------------------------------
+  stop = async () => {
+    if (this.#stopped) return;
+    this.#stopped = true;
+    await this.#closeForwards();
+    if (this.#ownsLifecycle) {
+      await this.#transport.stop(this.#workspace);
+    }
+  };
+  destroy = async () => {
+    this.#stopped = true;
+    await this.#closeForwards();
+    if (this.#ownsLifecycle) {
+      await this.#transport.destroy(this.#workspace);
+    }
+  };
+  /** Reduced view exposing only the base file/exec surface (no infra controls). */
+  restricted = () => ({
+    description: this.description,
+    readFile: this.readFile,
+    readBinaryFile: this.readBinaryFile,
+    readTextFile: this.readTextFile,
+    writeFile: this.writeFile,
+    writeBinaryFile: this.writeBinaryFile,
+    writeTextFile: this.writeTextFile,
+    spawn: this.spawn,
+    run: this.run
+  });
+  async #closeForwards() {
+    const forwards = [...this.#forwards.values()];
+    this.#forwards.clear();
+    await Promise.all(forwards.map((forward) => forward.then((f) => f.close()).catch(() => {
+    })));
+  }
+};
+function localScheme(protocol) {
+  switch (protocol) {
+    case "ws":
+      return "ws";
+    case "http":
+    case "https":
+      return "http";
+  }
+}
+
+// src/coder-workspace-provider.ts
+var CODER_WORKSPACE_PROVIDER_ID = "coder-workspace";
+var DEFAULT_BRIDGE_PORT = 4e3;
+var DEFAULT_WORKING_DIRECTORY = "/home/coder";
+var DEFAULT_READY_TIMEOUT_MS = 3e5;
+var READY_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_NAME_PREFIX = "agent";
+function createCoderWorkspace(settings) {
+  const transport = settings.transport ?? new CoderCliTransport();
+  const ports = settings.ports ?? [DEFAULT_BRIDGE_PORT];
+  const createMode = settings.create !== void 0;
+  const nameDerived = createMode && settings.workspace === void 0;
+  const readyTimeoutMs = settings.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+  const resolveWorkspace = (sessionId) => {
+    if (typeof settings.workspace === "function") return settings.workspace(sessionId);
+    if (typeof settings.workspace === "string") return settings.workspace;
+    if (settings.create !== void 0) {
+      const name = deriveWorkspaceName(
+        settings.create.namePrefix ?? DEFAULT_NAME_PREFIX,
+        sessionId
+      );
+      const owner = settings.create.owner;
+      return owner !== void 0 && owner !== "" ? `${owner}/${name}` : name;
+    }
+    throw new Error("createCoderWorkspace: set `workspace`, `create`, or both.");
+  };
+  const resolveOwnership = (createdByProvider) => {
+    if (!createMode) return settings.ownsLifecycle ?? false;
+    const owns = settings.ownsLifecycle ?? true;
+    return nameDerived ? owns : owns && createdByProvider;
+  };
+  const buildSession = async (workspace, abortSignal) => {
+    const { createdByProvider } = await ensureWorkspace(
+      transport,
+      workspace,
+      settings,
+      readyTimeoutMs,
+      abortSignal
+    );
+    const defaultWorkingDirectory = settings.defaultWorkingDirectory ?? await resolveHomeDirectory(transport, workspace, abortSignal);
+    const session = new CoderWorkspaceSession({
+      transport,
+      workspace,
+      id: workspace,
+      defaultWorkingDirectory,
+      ports: [...ports],
+      ownsLifecycle: resolveOwnership(createdByProvider)
+    });
+    return { session, createdByProvider };
+  };
+  return {
+    specificationVersion: "harness-sandbox-v1",
+    providerId: CODER_WORKSPACE_PROVIDER_ID,
+    // `bridgePorts` intentionally left undefined: this provider binds one
+    // workspace per session rather than leasing ports from a shared sandbox.
+    createSession: async (options) => {
+      const workspace = resolveWorkspace(options?.sessionId);
+      const { session, createdByProvider } = await buildSession(workspace, options?.abortSignal);
+      const shouldFirstCreate = createMode ? createdByProvider : settings.ownsLifecycle ?? false;
+      if (shouldFirstCreate && options?.onFirstCreate) {
+        await options.onFirstCreate(session.restricted(), {
+          abortSignal: options.abortSignal
+        });
+      }
+      return session;
+    },
+    resumeSession: async (options) => {
+      const workspace = resolveWorkspace(options.sessionId);
+      const { session } = await buildSession(workspace, options.abortSignal);
+      return session;
+    }
+  };
+}
+async function ensureWorkspace(transport, workspace, settings, readyTimeoutMs, abortSignal) {
+  const create = settings.create;
+  if (create === void 0) {
+    if (settings.ensureStarted) {
+      await transport.start(workspace, { abortSignal });
+    }
+    return { createdByProvider: false };
+  }
+  const existing = await transport.status(workspace, { abortSignal });
+  let createdByProvider = false;
+  if (existing === null) {
+    if (create.validate ?? true) {
+      await validatePreset(transport, create, abortSignal);
+    }
+    await transport.create(toCreateOptions(workspace, create, abortSignal));
+    createdByProvider = true;
+  } else {
+    if (create.ifExists === "error") {
+      throw new Error(
+        `createCoderWorkspace: workspace "${workspace}" already exists (create.ifExists: 'error').`
+      );
+    }
+    if (isStopped(existing)) {
+      await transport.start(workspace, { abortSignal });
+    }
+  }
+  await waitForReady(transport, workspace, readyTimeoutMs, abortSignal);
+  return { createdByProvider };
+}
+function isStopped(status) {
+  return status.buildStatus === "stopped" || status.buildStatus === "stopping" || status.transition === "stop";
+}
+function toCreateOptions(workspace, create, abortSignal) {
+  return {
+    workspace,
+    template: create.template,
+    templateVersion: create.templateVersion,
+    preset: create.preset,
+    parameters: stringifyParams(create.parameters),
+    parameterFile: create.parameterFile,
+    useParameterDefaults: create.useParameterDefaults,
+    ephemeralParameters: stringifyParams(create.ephemeralParameters),
+    stopAfter: create.stopAfter,
+    automaticUpdates: create.automaticUpdates,
+    org: create.org,
+    abortSignal
+  };
+}
+function stringifyParams(params) {
+  if (params === void 0) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(params)) {
+    out[key] = typeof value === "string" ? value : String(value);
+  }
+  return out;
+}
+async function validatePreset(transport, create, abortSignal) {
+  if (create.preset === void 0 || create.preset.toLowerCase() === "none") return;
+  let presets;
+  try {
+    presets = await transport.listPresets({
+      template: create.template,
+      templateVersion: create.templateVersion,
+      org: create.org,
+      abortSignal
+    });
+  } catch {
+    return;
+  }
+  if (presets.length === 0) return;
+  if (!presets.some((preset) => preset.name === create.preset)) {
+    const available = presets.map((preset) => `"${preset.name}"`).join(", ");
+    throw new Error(
+      `createCoderWorkspace: preset "${create.preset}" not found for template "${create.template}". Available presets: ${available || "(none)"}.`
+    );
+  }
+}
+async function waitForReady(transport, workspace, timeoutMs, abortSignal) {
+  const deadline = Date.now() + timeoutMs;
+  let last = "unknown";
+  for (; ; ) {
+    if (abortSignal?.aborted) throw abortSignal.reason ?? new Error("aborted");
+    const status = await transport.status(workspace, { abortSignal });
+    if (status !== null) {
+      last = `build=${status.buildStatus} agents=[` + status.agents.map((a) => `${a.name || "?"}:${a.status}/${a.lifecycleState}`).join(", ") + "]";
+      if (status.buildStatus === "failed") {
+        throw new Error(`createCoderWorkspace: workspace "${workspace}" build failed (${last}).`);
+      }
+      if (status.buildStatus === "canceled" || status.buildStatus === "deleted") {
+        throw new Error(
+          `createCoderWorkspace: workspace "${workspace}" is ${status.buildStatus} (${last}).`
+        );
+      }
+      const errored = status.agents.find(
+        (a) => a.lifecycleState === "start_error" || a.lifecycleState === "start_timeout"
+      );
+      if (errored) {
+        throw new Error(
+          `createCoderWorkspace: workspace "${workspace}" agent "${errored.name || "?"}" failed to start (lifecycle: ${errored.lifecycleState}).`
+        );
+      }
+      if (status.buildStatus === "running" && status.agents.some((a) => a.status === "connected" && a.lifecycleState === "ready")) {
+        return;
+      }
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `createCoderWorkspace: timed out after ${timeoutMs}ms waiting for workspace "${workspace}" to become ready (last status: ${last}).`
+      );
+    }
+    await delay(READY_POLL_INTERVAL_MS, void 0, { signal: abortSignal });
+  }
+}
+function deriveWorkspaceName(prefix, sessionId) {
+  if (sessionId === void 0 || sessionId === "") {
+    throw new Error(
+      "createCoderWorkspace: create mode needs either an explicit `workspace` or a sessionId to derive a fresh per-session workspace name from."
+    );
+  }
+  const hash = createHash("sha1").update(sessionId).digest("hex").slice(0, 12);
+  const cleanPrefix = sanitizeNameSegment(prefix) || DEFAULT_NAME_PREFIX;
+  return `${cleanPrefix}-${hash}`.slice(0, 32);
+}
+function sanitizeNameSegment(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function resolveHomeDirectory(transport, workspace, abortSignal) {
+  try {
+    const result = await transport.exec({
+      workspace,
+      command: 'printf %s "$HOME"',
+      abortSignal
+    });
+    const home = result.stdout.trim();
+    if (result.exitCode === 0 && home.startsWith("/")) {
+      return home;
+    }
+  } catch {
+  }
+  return DEFAULT_WORKING_DIRECTORY;
+}
+export {
+  CODER_WORKSPACE_PROVIDER_ID,
+  CoderCliTransport,
+  CoderWorkspaceSession,
+  createCoderWorkspace
+};