octoflow-core 1.0.0

package/dist/subpath-environments.cjs

@@ -0,0 +1,881 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/subpath-environments.ts
+var subpath_environments_exports = {};
+__export(subpath_environments_exports, {
+  EXECUTION_ENVIRONMENT_CONTRACT_VERSION: () => import_octoflow_protocols6.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+  createDockerEnvironment: () => createDockerEnvironment,
+  createE2bEnvironment: () => createE2bEnvironment,
+  createEnvironmentsPlugin: () => createEnvironmentsPlugin,
+  createEnvironmentsRegistry: () => createEnvironmentsRegistry,
+  createLocalEnvironment: () => createLocalEnvironment,
+  createSshEnvironment: () => createSshEnvironment,
+  createVercelSandboxEnvironment: () => createVercelSandboxEnvironment,
+  envBackedBashAction: () => envBackedBashAction
+});
+module.exports = __toCommonJS(subpath_environments_exports);
+
+// src/actions/define.ts
+function defineAction(opts) {
+  const {
+    name,
+    description,
+    parameters = {},
+    tags,
+    timeout,
+    metadata,
+    requireApproval,
+    permission
+  } = opts;
+  if (!name) throw new Error("[octoflow] defineAction: name is required");
+  if (!description) {
+    throw new Error("[octoflow] defineAction: description is required");
+  }
+  const shared = {
+    name,
+    description,
+    parameters,
+    tags,
+    timeout,
+    metadata,
+    requireApproval,
+    permission,
+    strict: opts.strict,
+    outputSchema: opts.outputSchema,
+    inputExamples: opts.inputExamples,
+    usageNotes: opts.usageNotes,
+    longDescription: opts.longDescription
+  };
+  if (opts.source) {
+    if (opts.execute) {
+      throw new Error(
+        `[octoflow] defineAction('${name}'): cannot set both 'execute' and 'source'`
+      );
+    }
+    return {
+      ...shared,
+      executor: {
+        type: "mcp",
+        server: opts.source.server,
+        tool: opts.source.tool,
+        invoke: opts.source.invoke,
+        timeoutMs: opts.source.timeoutMs,
+        schemaBudget: opts.source.schemaBudget
+      }
+    };
+  }
+  if (opts.execute === "cli") {
+    if (!opts.command) {
+      throw new Error(
+        `[octoflow] defineAction('${name}'): 'command' is required when execute is 'cli'`
+      );
+    }
+    return {
+      ...shared,
+      executor: {
+        type: "cli",
+        command: opts.command,
+        cwd: opts.cwd,
+        timeout: opts.timeout,
+        env: opts.env,
+        shell: opts.shell
+      }
+    };
+  }
+  if (typeof opts.execute === "function") {
+    return { ...shared, executor: { type: "function", fn: opts.execute } };
+  }
+  throw new Error(
+    `[octoflow] defineAction('${name}'): must provide 'execute' (function or 'cli') or 'source' (mcp)`
+  );
+}
+
+// src/environments/bash-action.ts
+function envBackedBashAction(env, opts = {}) {
+  return defineAction({
+    name: opts.name ?? "bash",
+    description: `Execute a shell command inside the '${env.name}' execution environment. Output is head+tail truncated when it exceeds the configured byte limit. Set \`workdir\` instead of running \`cd\` inside the command.`,
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "The shell command to execute."
+        },
+        workdir: {
+          type: "string",
+          description: "Working directory for the command."
+        },
+        env: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Extra environment variables for the command."
+        },
+        timeout_ms: {
+          type: "number",
+          description: "Maximum execution time in milliseconds before the process is killed."
+        },
+        stdin: {
+          type: "string",
+          description: "Optional stdin payload piped to the command."
+        }
+      },
+      required: ["command"]
+    },
+    execute: async (args) => {
+      const command = args.command;
+      const workdir = typeof args.workdir === "string" ? args.workdir : void 0;
+      const extraEnv = args.env != null && typeof args.env === "object" ? args.env : void 0;
+      const timeoutMs = typeof args.timeout_ms === "number" ? args.timeout_ms : void 0;
+      const stdin = typeof args.stdin === "string" ? args.stdin : void 0;
+      const result = await env.exec({
+        command,
+        cwd: workdir,
+        env: extraEnv,
+        timeoutMs,
+        stdin
+      });
+      return {
+        environment: env.name,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+        truncated: result.truncated,
+        timedOut: result.timedOut,
+        durationMs: result.durationMs,
+        ...result.costUsd != null ? { costUsd: result.costUsd } : {}
+      };
+    },
+    requireApproval: opts.requireApproval ?? true,
+    tags: opts.tags ?? ["shell", "bash", "exec", "environment", env.name]
+  });
+}
+
+// src/environments/docker.ts
+var import_octoflow_protocols = require("octoflow-protocols");
+
+// src/environments/shared.ts
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_OUTPUT_BYTE_LIMIT = 1048576;
+var SAFE_ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var ENVIRONMENT_DEFAULTS = {
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  outputByteLimit: DEFAULT_OUTPUT_BYTE_LIMIT
+};
+function truncateOutput(text, byteLimit) {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= byteLimit) {
+    return { text, truncated: false };
+  }
+  const tailBytes = Math.min(2048, Math.floor(byteLimit / 8));
+  const headBytes = byteLimit - tailBytes;
+  const head = buffer.subarray(0, headBytes).toString("utf8");
+  const tail = buffer.subarray(buffer.byteLength - tailBytes).toString("utf8");
+  return {
+    text: `${head}
+... [truncated ${buffer.byteLength - byteLimit} bytes] ...
+${tail}`,
+    truncated: true
+  };
+}
+var EnvironmentTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Environment exec timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "EnvironmentTimeoutError";
+  }
+  timeoutMs;
+};
+async function runWithTimeout(op, timeoutMs, outerSignal) {
+  if (outerSignal?.aborted) {
+    throw abortReasonToError(outerSignal.reason);
+  }
+  const controller = new AbortController();
+  let rejectAbort = () => {
+  };
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const abortWith = (error) => {
+    rejectAbort(error);
+    controller.abort(error);
+  };
+  const onAbort = () => abortWith(abortReasonToError(outerSignal?.reason));
+  outerSignal?.addEventListener("abort", onAbort, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    abortWith(new EnvironmentTimeoutError(timeoutMs));
+  }, timeoutMs);
+  try {
+    const value = await Promise.race([op(controller.signal), abortPromise]);
+    return { value, timedOut };
+  } finally {
+    clearTimeout(timer);
+    outerSignal?.removeEventListener("abort", onAbort);
+  }
+}
+function isEnvironmentTimeoutError(error) {
+  return error instanceof EnvironmentTimeoutError;
+}
+function timedOutExecResult(error, startedAtMs) {
+  return {
+    stdout: "",
+    stderr: `${error.message}
+`,
+    exitCode: 124,
+    truncated: false,
+    timedOut: true,
+    durationMs: Date.now() - startedAtMs
+  };
+}
+function assertSafeEnvKey(key) {
+  if (!SAFE_ENV_KEY_RE.test(key)) {
+    throw new Error(`Unsafe environment variable name: ${key}`);
+  }
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function abortReasonToError(reason) {
+  if (reason instanceof Error) return reason;
+  if (reason == null) return new Error("Environment exec aborted");
+  if (typeof reason === "string") return new Error(reason);
+  if (typeof reason === "number" || typeof reason === "boolean" || typeof reason === "bigint") {
+    return new Error(String(reason));
+  }
+  return new Error("Environment exec aborted");
+}
+async function runExecBody(input, defaultTimeoutMs, outputByteLimit, executor) {
+  const start = Date.now();
+  const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+  let value;
+  let timedOut;
+  try {
+    ({ value, timedOut } = await runWithTimeout(
+      async () => executor(),
+      timeoutMs,
+      input.signal
+    ));
+  } catch (error) {
+    if (isEnvironmentTimeoutError(error)) {
+      return timedOutExecResult(error, start);
+    }
+    throw error;
+  }
+  const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);
+  const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);
+  return {
+    stdout: stdoutTrunc.text,
+    stderr: stderrTrunc.text,
+    exitCode: value.exitCode,
+    truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+    timedOut,
+    durationMs: Date.now() - start
+  };
+}
+async function loadOptionalPeer(packageName) {
+  try {
+    return await import(packageName);
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[octoflow-core/environments] missing optional peer '${packageName}'. Install it first: \`yarn add ${packageName}\`. Original error: ${cause}`
+    );
+  }
+}
+
+// src/environments/docker.ts
+var DOCKER_CAPABILITIES = [
+  "sandboxed",
+  "process-backed",
+  "sdk-backed"
+];
+function createDockerEnvironment(opts) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  let containerPromise;
+  let ownsContainer = false;
+  async function getContainer() {
+    if (containerPromise) return containerPromise;
+    containerPromise = (async () => {
+      const client = opts.client ?? await createDockerodeClient(opts.dockerOptions);
+      if (opts.containerId) {
+        return client.getContainer(opts.containerId);
+      }
+      ownsContainer = true;
+      const container = await client.createContainer({
+        Image: opts.image,
+        Cmd: opts.cmd ?? ["sleep", "infinity"],
+        WorkingDir: opts.workingDir,
+        Tty: false
+      });
+      await container.start();
+      return container;
+    })();
+    return containerPromise;
+  }
+  return {
+    contractVersion: import_octoflow_protocols.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "docker",
+    capabilities: DOCKER_CAPABILITIES,
+    async exec(input) {
+      const container = await getContainer();
+      return runExecBody(
+        input,
+        defaultTimeoutMs,
+        outputByteLimit,
+        () => execInContainer(container, input)
+      );
+    },
+    async cleanup() {
+      if (!containerPromise || !ownsContainer) return;
+      const container = await containerPromise;
+      try {
+        await container.stop({ t: 1 });
+      } catch {
+      }
+      try {
+        await container.remove({ force: true });
+      } catch {
+      }
+      containerPromise = void 0;
+    }
+  };
+}
+async function createDockerodeClient(dockerOptions) {
+  const mod = await loadOptionalPeer("dockerode");
+  return new mod.default(dockerOptions);
+}
+async function execInContainer(container, input) {
+  const env = input.env ? Object.entries(input.env).map(([k, v]) => `${k}=${v}`) : void 0;
+  const exec = await container.exec({
+    Cmd: ["/bin/sh", "-c", input.command],
+    AttachStdout: true,
+    AttachStderr: true,
+    AttachStdin: input.stdin != null,
+    Tty: false,
+    WorkingDir: input.cwd,
+    Env: env
+  });
+  const stream = await exec.start({ hijack: true, stdin: input.stdin != null });
+  const { stdout, stderr } = await collectDemuxedStream(stream, input.stdin);
+  const inspect = await exec.inspect();
+  return {
+    stdout,
+    stderr,
+    exitCode: inspect.ExitCode ?? 0
+  };
+}
+function collectDemuxedStream(stream, stdin) {
+  return new Promise((resolve, reject) => {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let leftover = Buffer.alloc(0);
+    stream.on("data", (chunk) => {
+      let buf = Buffer.concat([leftover, chunk]);
+      while (buf.byteLength >= 8) {
+        const header = buf.subarray(0, 8);
+        const streamId = header.readUInt8(0);
+        const payloadLen = header.readUInt32BE(4);
+        if (buf.byteLength < 8 + payloadLen) break;
+        const payload = buf.subarray(8, 8 + payloadLen);
+        if (streamId === 2) stderrChunks.push(payload);
+        else stdoutChunks.push(payload);
+        buf = buf.subarray(8 + payloadLen);
+      }
+      leftover = buf;
+    });
+    stream.on("error", reject);
+    stream.on("end", () => {
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8")
+      });
+    });
+    const writable = stream;
+    if (stdin != null && typeof writable.end === "function") {
+      writable.end(stdin);
+    }
+  });
+}
+
+// src/environments/e2b.ts
+var import_octoflow_protocols2 = require("octoflow-protocols");
+var E2B_CAPABILITIES = [
+  "sandboxed",
+  "serverless",
+  "sdk-backed",
+  "persistent-snapshot"
+];
+function createE2bEnvironment(opts) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  let sandboxPromise;
+  async function getSandbox() {
+    if (sandboxPromise) return sandboxPromise;
+    sandboxPromise = createOrConnect(opts);
+    return sandboxPromise;
+  }
+  return {
+    contractVersion: import_octoflow_protocols2.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "e2b",
+    capabilities: E2B_CAPABILITIES,
+    async exec(input) {
+      const start = Date.now();
+      const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+      const sandbox = await getSandbox();
+      let value;
+      let timedOut;
+      try {
+        ({ value, timedOut } = await runWithTimeout(
+          async () => sandbox.commands.run(input.command, {
+            cwd: input.cwd,
+            envs: input.env,
+            stdin: input.stdin
+          }),
+          timeoutMs,
+          input.signal
+        ));
+      } catch (error) {
+        if (isEnvironmentTimeoutError(error)) {
+          return timedOutExecResult(error, start);
+        }
+        throw error;
+      }
+      const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);
+      const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);
+      return {
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        exitCode: value.exitCode,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        timedOut,
+        durationMs: Date.now() - start
+      };
+    },
+    async snapshot(taskId) {
+      const sandbox = await getSandbox();
+      if (!sandbox.pause) {
+        throw new Error(
+          "[octoflow-core/environments] e2b: sandbox.pause() unavailable on this SDK version"
+        );
+      }
+      const result = await sandbox.pause();
+      return { id: result.id, metadata: { taskId } };
+    },
+    async restore(_taskId, ref) {
+      const mod = await loadOptionalPeer("@e2b/code-interpreter");
+      if (!mod.Sandbox.connect) {
+        throw new Error(
+          "[octoflow-core/environments] e2b: Sandbox.connect() unavailable on this SDK version"
+        );
+      }
+      sandboxPromise = mod.Sandbox.connect(ref.id, { apiKey: opts.apiKey });
+      const sandbox = await sandboxPromise;
+      await sandbox.resume?.(ref.id);
+    },
+    async cleanup() {
+      if (!sandboxPromise) return;
+      const sandbox = await sandboxPromise;
+      try {
+        await sandbox.kill?.();
+      } catch {
+      }
+      sandboxPromise = void 0;
+    }
+  };
+}
+async function createOrConnect(opts) {
+  if (opts.sandbox) return opts.sandbox;
+  const mod = await loadOptionalPeer("@e2b/code-interpreter");
+  if (opts.sandboxId && mod.Sandbox.connect) {
+    return mod.Sandbox.connect(opts.sandboxId, { apiKey: opts.apiKey });
+  }
+  return mod.Sandbox.create({ apiKey: opts.apiKey, template: opts.template });
+}
+
+// src/environments/local.ts
+var import_node_child_process = require("node:child_process");
+var import_octoflow_protocols3 = require("octoflow-protocols");
+var LOCAL_CAPABILITIES = [
+  "process-backed",
+  "long-lived"
+];
+function createLocalEnvironment(opts = {}) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  const shell = opts.shell !== false;
+  return {
+    contractVersion: import_octoflow_protocols3.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "local",
+    capabilities: LOCAL_CAPABILITIES,
+    async exec(input) {
+      const start = Date.now();
+      const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+      const cwd = input.cwd ?? opts.cwd;
+      const mergedEnv = { ...process.env, ...opts.env, ...input.env };
+      let value;
+      let timedOut;
+      try {
+        ({ value, timedOut } = await runWithTimeout(
+          (signal) => execOnce({ input, cwd, env: mergedEnv, shell, signal }),
+          timeoutMs,
+          input.signal
+        ));
+      } catch (error) {
+        if (isEnvironmentTimeoutError(error)) {
+          return timedOutExecResult(error, start);
+        }
+        throw error;
+      }
+      const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);
+      const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);
+      return {
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        exitCode: value.exitCode,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        timedOut,
+        durationMs: Date.now() - start
+      };
+    },
+    cleanup() {
+      return Promise.resolve();
+    }
+  };
+}
+function execOnce(args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(args.input.command, [], {
+      cwd: args.cwd,
+      env: args.env,
+      shell: args.shell,
+      signal: args.signal,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+    child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+    if (child.stdin) {
+      child.stdin.end(args.input.stdin);
+    }
+    child.on("error", (err) => {
+      stderrChunks.push(Buffer.from(`
+${err.message}
+`, "utf8"));
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        exitCode: typeof err.errno === "number" ? err.errno : 1
+      });
+    });
+    child.on("close", (code, signal) => {
+      const exitCode = code ?? (signal ? 128 + signalNumber(signal) : 1);
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        exitCode
+      });
+    });
+  });
+}
+function signalNumber(signal) {
+  const signals = {
+    SIGINT: 2,
+    SIGKILL: 9,
+    SIGTERM: 15
+  };
+  return signals[signal] ?? 1;
+}
+
+// src/environments/registry.ts
+function createEnvironmentsRegistry(opts) {
+  const names = Object.keys(opts.environments);
+  if (names.length === 0) {
+    throw new Error(
+      "[octoflow-core/environments] registry requires at least one environment"
+    );
+  }
+  const defaultName = resolveDefaultName(opts);
+  if (!opts.environments[defaultName]) {
+    throw new Error(
+      `[octoflow-core/environments] default environment '${defaultName}' is not in the registry`
+    );
+  }
+  for (const [worker, target] of Object.entries(opts.perPackWorker ?? {})) {
+    if (!opts.environments[target]) {
+      throw new Error(
+        `[octoflow-core/environments] perPackWorker['${worker}'] points at unknown environment '${target}'`
+      );
+    }
+  }
+  return {
+    defaultName,
+    list() {
+      return Object.freeze([...names]);
+    },
+    has(name) {
+      return Object.prototype.hasOwnProperty.call(opts.environments, name);
+    },
+    get(name) {
+      const target = name ?? defaultName;
+      const env = opts.environments[target];
+      if (!env) {
+        throw new Error(
+          `[octoflow-core/environments] unknown environment '${target}'`
+        );
+      }
+      return env;
+    },
+    forWorker(workerName) {
+      const pinned = opts.perPackWorker?.[workerName];
+      return this.get(pinned ?? defaultName);
+    },
+    async cleanupAll() {
+      await Promise.allSettled(
+        Object.values(opts.environments).map((env) => env.cleanup())
+      );
+    }
+  };
+}
+function resolveDefaultName(opts) {
+  if (opts.defaultName) return opts.defaultName;
+  const names = Object.keys(opts.environments);
+  if (names.length === 1) return names[0];
+  throw new Error(
+    `[octoflow-core/environments] more than one environment registered (${names.join(", ")}); set 'defaultName' explicitly`
+  );
+}
+
+// src/environments/plugin.ts
+function createEnvironmentsPlugin(opts) {
+  const registry = createEnvironmentsRegistry(opts);
+  const installBash = opts.installBashAction !== false;
+  const actions = installBash ? [envBackedBashAction(registry.get(), { name: opts.bashActionName })] : [];
+  return {
+    name: "octoflow-environments",
+    version: "0.1.0",
+    actions,
+    environments: registry,
+    async teardown(_ctx) {
+      await registry.cleanupAll();
+    }
+  };
+}
+
+// src/environments/ssh.ts
+var import_octoflow_protocols4 = require("octoflow-protocols");
+var SSH_CAPABILITIES = [
+  "process-backed",
+  "long-lived"
+];
+function createSshEnvironment(opts) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  let clientPromise;
+  async function getClient() {
+    if (clientPromise) return clientPromise;
+    clientPromise = connectClient(opts);
+    return clientPromise;
+  }
+  return {
+    contractVersion: import_octoflow_protocols4.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "ssh",
+    capabilities: SSH_CAPABILITIES,
+    async exec(input) {
+      const client = await getClient();
+      return runExecBody(
+        input,
+        defaultTimeoutMs,
+        outputByteLimit,
+        () => execOverChannel(client, input)
+      );
+    },
+    async cleanup() {
+      if (!clientPromise) return;
+      const client = await clientPromise;
+      try {
+        client.end();
+      } catch {
+      }
+      clientPromise = void 0;
+    }
+  };
+}
+async function connectClient(opts) {
+  const client = opts.client ?? await loadDefaultClient();
+  return new Promise((resolve, reject) => {
+    client.once("ready", () => resolve(client));
+    client.once("error", (err) => reject(err));
+    client.connect({
+      host: opts.host,
+      port: opts.port ?? 22,
+      username: opts.username,
+      password: opts.password,
+      privateKey: opts.privateKey,
+      passphrase: opts.passphrase,
+      ...opts.connectOptions
+    });
+  });
+}
+async function loadDefaultClient() {
+  const mod = await loadOptionalPeer("ssh2");
+  return new mod.Client();
+}
+function execOverChannel(client, input) {
+  const envEntries = input.env ? Object.entries(input.env) : [];
+  const command = composeCommand(input.command, input.cwd, envEntries);
+  return new Promise((resolve, reject) => {
+    client.exec(command, {}, (err, channel) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      const stdoutChunks = [];
+      const stderrChunks = [];
+      let exitCode = 0;
+      channel.on("data", (chunk) => stdoutChunks.push(chunk));
+      channel.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+      channel.on("error", reject);
+      channel.on("close", (code) => {
+        exitCode = code ?? 0;
+        resolve({
+          stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+          stderr: Buffer.concat(stderrChunks).toString("utf8"),
+          exitCode
+        });
+      });
+      channel.end(input.stdin);
+    });
+  });
+}
+function composeCommand(command, cwd, envEntries = []) {
+  const exports2 = envEntries.map(([k, v]) => {
+    assertSafeEnvKey(k);
+    return `export ${k}=${shellQuote(v)}`;
+  }).join("; ");
+  const cd = cwd ? `cd ${shellQuote(cwd)}` : "";
+  const prefix = [exports2, cd].filter(Boolean).join(" && ");
+  return prefix ? `${prefix} && ${command}` : command;
+}
+
+// src/environments/vercel-sandbox.ts
+var import_octoflow_protocols5 = require("octoflow-protocols");
+var VERCEL_CAPABILITIES = [
+  "sandboxed",
+  "serverless",
+  "sdk-backed"
+];
+function createVercelSandboxEnvironment(opts) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  let sandboxPromise;
+  async function getSandbox() {
+    if (sandboxPromise) return sandboxPromise;
+    sandboxPromise = createOrGetSandbox(opts);
+    return sandboxPromise;
+  }
+  return {
+    contractVersion: import_octoflow_protocols5.EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "vercel-sandbox",
+    capabilities: VERCEL_CAPABILITIES,
+    async exec(input) {
+      const start = Date.now();
+      const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+      const sandbox = await getSandbox();
+      let value;
+      let timedOut;
+      try {
+        ({ value, timedOut } = await runWithTimeout(
+          async () => sandbox.runCommand({
+            command: input.command,
+            cwd: input.cwd,
+            env: input.env,
+            stdin: input.stdin
+          }),
+          timeoutMs,
+          input.signal
+        ));
+      } catch (error) {
+        if (isEnvironmentTimeoutError(error)) {
+          return timedOutExecResult(error, start);
+        }
+        throw error;
+      }
+      const stdout = await Promise.resolve(value.stdout());
+      const stderr = await Promise.resolve(value.stderr());
+      const stdoutTrunc = truncateOutput(stdout, outputByteLimit);
+      const stderrTrunc = truncateOutput(stderr, outputByteLimit);
+      return {
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        exitCode: value.exitCode,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        timedOut,
+        durationMs: value.durationMs ?? Date.now() - start,
+        ...value.costUsd != null ? { costUsd: value.costUsd } : {}
+      };
+    },
+    async cleanup() {
+      if (!sandboxPromise) return;
+      const sandbox = await sandboxPromise;
+      try {
+        await sandbox.stop?.();
+      } catch {
+      }
+      sandboxPromise = void 0;
+    }
+  };
+}
+async function createOrGetSandbox(opts) {
+  if (opts.sandbox) return opts.sandbox;
+  const mod = await loadOptionalPeer("@vercel/sandbox");
+  if (opts.sandboxId && mod.Sandbox.get) {
+    return mod.Sandbox.get({
+      team: opts.team,
+      token: opts.token,
+      sandboxId: opts.sandboxId
+    });
+  }
+  return mod.Sandbox.create({
+    team: opts.team,
+    token: opts.token,
+    projectId: opts.projectId,
+    image: opts.image
+  });
+}
+
+// src/environments/index.ts
+var import_octoflow_protocols6 = require("octoflow-protocols");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+  createDockerEnvironment,
+  createE2bEnvironment,
+  createEnvironmentsPlugin,
+  createEnvironmentsRegistry,
+  createLocalEnvironment,
+  createSshEnvironment,
+  createVercelSandboxEnvironment,
+  envBackedBashAction
+});
+//# sourceMappingURL=subpath-environments.cjs.map