@sema-agent/server 1.185.0

package/dist/plugins/remote-env-host.js

@@ -0,0 +1,868 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { armPipeDestroyGrace } from "./remote-shell.js";
+import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys } from "./host-platform.js";
+import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
+import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+const PROVIDER = "host";
+const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+const HOST_BG_MAX_CONCURRENT = Math.max(1, Math.floor(Number(process.env.HOST_BG_MAX_CONCURRENT ?? "")) || 8);
+const HOST_BG_DEFAULT_TIMEOUT_SEC = Math.max(1, Math.floor(Number(process.env.HOST_BG_DEFAULT_TIMEOUT_SEC ?? "")) || 300);
+const HOST_BG_MAX_TIMEOUT_SEC = Math.max(HOST_BG_DEFAULT_TIMEOUT_SEC, Math.floor(Number(process.env.HOST_BG_MAX_TIMEOUT_SEC ?? "")) || 1800);
+const HOST_BG_READ_CAP = Math.max(64 * 1024, Math.floor(Number(process.env.HOST_BG_READ_CAP ?? "")) || 1024 * 1024);
+const HOST_BG_FILE_CAP = Math.max(HOST_BG_READ_CAP, Math.floor(Number(process.env.HOST_BG_FILE_CAP ?? "")) || 64 * 1024 * 1024);
+const HOST_BG_KILL_GRACE_MS = Math.max(0, Math.floor(Number(process.env.HOST_BG_KILL_GRACE_MS ?? "")) || 1000);
+const HOST_BG_MEM_CAP = Math.max(64 * 1024, Math.floor(Number(process.env.HOST_BG_MEM_CAP ?? "")) || 8 * 1024 * 1024);
+const ok = (value) => ({ ok: true, value });
+const unsupported = (op) => ({
+    ok: false,
+    error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
+});
+const UNSUPPORTED_SCHEDULER_CAPS = {
+    supported: false,
+    maxScheduledPerScope: 0,
+    minDelaySec: 0,
+    minCronIntervalSec: 0,
+    maxScheduledHorizonSec: 0,
+};
+export class RemoteHostExecutionEnv {
+    capabilities = { isolation: false, suspendable: false };
+    get schedulerCapabilities() {
+        return this.cfg.scheduler?.schedulerCapabilities ?? UNSUPPORTED_SCHEDULER_CAPS;
+    }
+    schedule(intent, ctx) {
+        return this.cfg.scheduler
+            ? this.cfg.scheduler.schedule(intent, ctx)
+            : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
+    }
+    cancel(id, ctx) {
+        return this.cfg.scheduler
+            ? this.cfg.scheduler.cancel(id, ctx)
+            : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
+    }
+    list(ctx) {
+        return this.cfg.scheduler
+            ? this.cfg.scheduler.list(ctx)
+            : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
+    }
+    cwd;
+    workspaceDir;
+    cfg;
+    prepared = false;
+    destroyed = false;
+    persistent;
+    preparing;
+    handle;
+    constructor(config = {}) {
+        if (config.workspaceDir) {
+            this.workspaceDir = path.resolve(config.workspaceDir);
+            this.persistent = true;
+        }
+        else {
+            const base = config.workspaceBase ?? os.tmpdir();
+            const id = config.id ?? randomBytes(6).toString("hex");
+            const suffix = randomBytes(4).toString("hex");
+            this.workspaceDir = path.resolve(base, `sema-host-${sanitizeId(id)}-${suffix}`);
+            this.persistent = false;
+        }
+        this.cfg = {
+            ...config,
+            commandTimeoutMs: config.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+        };
+        this.cwd = this.workspaceDir;
+        this.handle = { sandboxId: this.workspaceDir, provider: PROVIDER, mountPath: this.workspaceDir };
+    }
+    workspaceHandle() {
+        return this.handle;
+    }
+    async connect(config) {
+        if (config?.snapshotId)
+            return unsupported("connect(snapshotId)");
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (config?.abortSignal?.aborted)
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
+        try {
+            await this.ensurePrepared();
+        }
+        catch (e) {
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
+        }
+        if (config?.secrets?.length) {
+        }
+        return ok(this.handle);
+    }
+    async suspendVM(_options) {
+        return unsupported("suspendVM");
+    }
+    async resumeVM(_snapshotId, _options) {
+        return unsupported("resumeVM");
+    }
+    async postResumeInit() {
+        return unsupported("postResumeInit");
+    }
+    async reconnect(_sessionToken) {
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        return ok(this.handle);
+    }
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        const p = this.preparing;
+        this.preparing = undefined;
+        try {
+            await p?.catch(() => { });
+        }
+        finally {
+            if (this.persistent)
+                return;
+            try {
+                await fs.rm(this.workspaceDir, { recursive: true, force: true });
+            }
+            catch {
+            }
+        }
+    }
+    async cleanup() {
+        return this.destroy();
+    }
+    get backgroundCapabilities() {
+        return {
+            supported: (this.cfg.backgroundShell ?? true) && process.env.HOST_BG_DISABLED !== "true",
+            maxConcurrent: HOST_BG_MAX_CONCURRENT,
+            defaultBgTimeoutSec: HOST_BG_DEFAULT_TIMEOUT_SEC,
+            maxBgTimeoutSec: HOST_BG_MAX_TIMEOUT_SEC,
+            supportsDetach: (this.cfg.backgroundShell ?? true) && process.env.HOST_BG_DISABLED !== "true",
+        };
+    }
+    _bgManager;
+    get bgManager() {
+        return (this._bgManager ??= new BackgroundShellManager(this.makeBgDriver(), this.backgroundCapabilities));
+    }
+    makeBgDriver() {
+        const self = this;
+        return {
+            async launch(command, options, ctx) {
+                const ready = await self.shellReady();
+                if (!ready.ok)
+                    throw new BackgroundShellError("spawn_failed", ready.error.message);
+                const dir = path.join(self.workspaceDir, ".sema-bg", randomBytes(8).toString("hex"));
+                await fs.mkdir(dir, { recursive: true });
+                const outPath = path.join(dir, "out");
+                const errPath = path.join(dir, "err");
+                const outFh = await fs.open(outPath, "w");
+                const errFh = await fs.open(errPath, "w");
+                let child;
+                try {
+                    const sh = hostShell();
+                    child = spawn(sh.shell, [...sh.args, command], {
+                        cwd: self.resolve(options?.cwd ?? self.cwd),
+                        env: self.mergeEnv(options?.env),
+                        ...spawnGroupOptions(),
+                        stdio: ["ignore", outFh.fd, errFh.fd],
+                    });
+                }
+                catch (e) {
+                    await outFh.close().catch(() => { });
+                    await errFh.close().catch(() => { });
+                    await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+                    throw new BackgroundShellError("spawn_failed", e instanceof Error ? e.message : String(e), e);
+                }
+                const pid = child.pid;
+                if (pid != null) {
+                    child.on("close", (code, signal) => ctx.onTerminal(false, code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0)));
+                    child.on("error", () => ctx.onTerminal(true));
+                    child.unref();
+                }
+                await outFh.close().catch(() => { });
+                await errFh.close().catch(() => { });
+                if (pid == null) {
+                    await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+                    throw new BackgroundShellError("spawn_failed", "host background spawn produced no pid");
+                }
+                return { pid, dir, outPath, errPath, stdoutCursor: 0, stderrCursor: 0 };
+            },
+            async read(state) {
+                if (state.mem) {
+                    const o = drainMemStream(state.mem.out);
+                    const e = drainMemStream(state.mem.err);
+                    return {
+                        stdout: o.text,
+                        stderr: e.text,
+                        bytesFromStart: state.mem.out.totalBytes + state.mem.err.totalBytes,
+                        bytesDroppedBeforeCursor: o.dropped + e.dropped,
+                    };
+                }
+                const readForward = async (p, cursor) => {
+                    let fh;
+                    try {
+                        fh = await fs.open(p, "r");
+                    }
+                    catch {
+                        return { chunk: "", cursor, size: cursor };
+                    }
+                    try {
+                        const { size } = await fh.stat();
+                        if (size <= cursor)
+                            return { chunk: "", cursor: size, size };
+                        const n = Math.min(size - cursor, HOST_BG_READ_CAP);
+                        const buf = Buffer.alloc(n);
+                        await fh.read(buf, 0, n, cursor);
+                        return { chunk: buf.toString("utf8"), cursor: cursor + n, size };
+                    }
+                    finally {
+                        await fh.close().catch(() => { });
+                    }
+                };
+                const o = await readForward(state.outPath, state.stdoutCursor);
+                const e = await readForward(state.errPath, state.stderrCursor);
+                state.stdoutCursor = o.cursor;
+                state.stderrCursor = e.cursor;
+                let terminal;
+                if (o.size > HOST_BG_FILE_CAP || e.size > HOST_BG_FILE_CAP) {
+                    try {
+                        killTreeHard(state.pid);
+                    }
+                    catch { }
+                    terminal = { failed: true };
+                }
+                return {
+                    stdout: o.chunk,
+                    stderr: e.chunk,
+                    bytesFromStart: o.size + e.size,
+                    bytesDroppedBeforeCursor: 0,
+                    ...(terminal ? { terminal } : {}),
+                };
+            },
+            async kill(state) {
+                try {
+                    killTreeSoft(state.pid);
+                }
+                catch {
+                    return;
+                }
+                setTimeout(() => { try {
+                    killTreeHard(state.pid);
+                }
+                catch { } }, HOST_BG_KILL_GRACE_MS).unref?.();
+            },
+            async disposeOne(state) {
+                state.detachCleanup?.();
+                try {
+                    killTreeHard(state.pid);
+                }
+                catch { }
+                if (state.dir)
+                    await fs.rm(state.dir, { recursive: true, force: true }).catch(() => { });
+            },
+        };
+    }
+    spawnBackground(command, options) {
+        return this.bgManager.spawn(command, options);
+    }
+    adoptRunningExec(child, memOut, memErr) {
+        const pid = child.pid;
+        if (pid == null)
+            return undefined;
+        const adopted = this.bgManager.adoptSync((ctx) => {
+            const mem = { out: memOut, err: memErr };
+            const onOut = (d) => feedMemStream(mem.out, d, HOST_BG_MEM_CAP);
+            const onErr = (d) => feedMemStream(mem.err, d, HOST_BG_MEM_CAP);
+            child.stdout?.on("data", onOut);
+            child.stderr?.on("data", onErr);
+            const onClose = (code, signal) => ctx.onTerminal(false, code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0));
+            const onErrEvt = () => ctx.onTerminal(true);
+            child.on("close", onClose);
+            child.on("error", onErrEvt);
+            if (child.exitCode !== null || child.signalCode !== null)
+                ctx.onTerminal(false, child.exitCode ?? (child.signalCode ? 128 + (signalNumber(child.signalCode) ?? 9) : 0));
+            child.unref?.();
+            const detachCleanup = () => {
+                child.stdout?.off("data", onOut);
+                child.stderr?.off("data", onErr);
+                child.off("close", onClose);
+                child.off("error", onErrEvt);
+            };
+            return { pid, stdoutCursor: 0, stderrCursor: 0, mem, detachCleanup };
+        });
+        return adopted?.shellId;
+    }
+    pollBackground(shellId) {
+        return this.bgManager.poll(shellId);
+    }
+    killBackground(shellId) {
+        return this.bgManager.kill(shellId);
+    }
+    disposeBackgroundShells(opts) {
+        return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
+    }
+    async exec(command, options) {
+        if (options?.abortSignal?.aborted)
+            return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
+        const ready = await this.shellReady();
+        if (!ready.ok)
+            return ready;
+        const cwd = this.resolve(options?.cwd ?? this.cwd);
+        const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs;
+        const detachSignal = options?.detachSignal;
+        return new Promise((resolve) => {
+            const outBuf = new RollingTailBuffer();
+            const errBuf = new RollingTailBuffer();
+            const tee = detachSignal ? { out: seedMemStream(""), err: seedMemStream("") } : undefined;
+            let settled = false;
+            let forceSettleTimer;
+            const sh = hostShell();
+            const child = spawn(sh.shell, [...sh.args, command], {
+                cwd,
+                env: this.mergeEnv(options?.env),
+                ...spawnGroupOptions(),
+            });
+            const finish = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                options?.abortSignal?.removeEventListener("abort", onAbort);
+                removeDetachListener?.();
+                resolve(r);
+            };
+            let removeDetachListener;
+            const kill = () => {
+                try {
+                    if (child.pid != null)
+                        killTreeHard(child.pid);
+                }
+                catch {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch { }
+                }
+                forceSettleTimer ??= armPipeDestroyGrace(child);
+            };
+            const timer = setTimeout(() => {
+                kill();
+                finish({ ok: false, error: new ExecutionError("timeout", `host exec exceeded ${timeoutMs}ms`) });
+            }, timeoutMs);
+            const onAbort = () => {
+                kill();
+                finish({ ok: false, error: new ExecutionError("aborted", "host exec aborted") });
+            };
+            if (options?.abortSignal)
+                options.abortSignal.addEventListener("abort", onAbort, { once: true });
+            const onDetach = () => {
+                if (settled)
+                    return;
+                const out = outBuf.result();
+                const err = errBuf.result();
+                child.stdout?.off("data", onExecOut);
+                child.stderr?.off("data", onExecErr);
+                const shellId = this.adoptRunningExec(child, tee.out, tee.err);
+                const seedOut = markTruncated(out.text, out.droppedBytes);
+                const seedErr = markTruncated(err.text, err.droppedBytes);
+                if (shellId === undefined) {
+                    child.stdout?.on("data", onExecOut);
+                    child.stderr?.on("data", onExecErr);
+                    return;
+                }
+                clearTimeout(timer);
+                if (forceSettleTimer)
+                    clearTimeout(forceSettleTimer);
+                options?.abortSignal?.removeEventListener("abort", onAbort);
+                settled = true;
+                resolve(ok({ stdout: seedOut, stderr: seedErr, exitCode: 0, detached: { shellId } }));
+            };
+            const onExecOut = (d) => { outBuf.push(d); if (tee)
+                feedMemStream(tee.out, d, HOST_BG_MEM_CAP); options?.onStdout?.(d.toString()); };
+            const onExecErr = (d) => { errBuf.push(d); if (tee)
+                feedMemStream(tee.err, d, HOST_BG_MEM_CAP); options?.onStderr?.(d.toString()); };
+            child.stdout?.on("data", onExecOut);
+            child.stderr?.on("data", onExecErr);
+            if (detachSignal) {
+                if (detachSignal.aborted)
+                    onDetach();
+                else {
+                    detachSignal.addEventListener("abort", onDetach, { once: true });
+                    removeDetachListener = () => detachSignal.removeEventListener("abort", onDetach);
+                }
+            }
+            child.on("error", (e) => {
+                finish({ ok: false, error: new ExecutionError("spawn_error", `host spawn failed: ${e.message}`, e) });
+            });
+            child.on("close", (code, signal) => {
+                if (forceSettleTimer)
+                    clearTimeout(forceSettleTimer);
+                const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
+                const out = outBuf.result();
+                const err = errBuf.result();
+                finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr: markTruncated(err.text, err.droppedBytes), exitCode }));
+            });
+        });
+    }
+    async *execStream(command, options) {
+        const ready = await this.shellReady();
+        if (!ready.ok)
+            throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
+        const cwd = this.resolve(options?.cwd ?? this.cwd);
+        const timeoutMs = options?.timeout != null ? options.timeout * 1000 : undefined;
+        const idleMs = options?.readTimeoutMs;
+        const cap = options?.maxOutputBytes;
+        const queue = [];
+        let finished = false;
+        let failure;
+        let exitCode = 0;
+        let bytes = 0;
+        let lastChunk = Date.now();
+        let wake;
+        const signalReady = () => { const w = wake; wake = undefined; w?.(); };
+        const sh = hostShell();
+        const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env), ...spawnGroupOptions() });
+        let pipeDestroyTimer;
+        const kill = () => {
+            try {
+                if (child.pid != null)
+                    killTreeHard(child.pid);
+            }
+            catch {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { }
+            }
+            pipeDestroyTimer ??= armPipeDestroyGrace(child);
+        };
+        const enqueue = (type, data) => {
+            if (finished)
+                return;
+            bytes += Buffer.byteLength(data, "utf8");
+            lastChunk = Date.now();
+            queue.push({ type, data });
+            signalReady();
+        };
+        child.stdout?.on("data", (d) => enqueue("stdout", d.toString()));
+        child.stderr?.on("data", (d) => enqueue("stderr", d.toString()));
+        child.on("error", (e) => {
+            if (finished)
+                return;
+            failure = new RemoteExecutionError("connect_failed", `host spawn failed: ${e.message}`, e);
+            finished = true;
+            signalReady();
+        });
+        child.on("close", (code, signal) => {
+            if (pipeDestroyTimer)
+                clearTimeout(pipeDestroyTimer);
+            if (finished)
+                return;
+            exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
+            finished = true;
+            signalReady();
+        });
+        const onAbort = () => {
+            if (finished)
+                return;
+            failure = new RemoteExecutionError("aborted", "execStream aborted");
+            finished = true;
+            kill();
+            signalReady();
+        };
+        if (options?.signal) {
+            if (options.signal.aborted)
+                onAbort();
+            else
+                options.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        const wallTimer = timeoutMs != null
+            ? setTimeout(() => {
+                if (finished)
+                    return;
+                failure = new RemoteExecutionError("timeout", `execStream exceeded ${timeoutMs}ms`);
+                finished = true;
+                kill();
+                signalReady();
+            }, timeoutMs)
+            : undefined;
+        wallTimer?.unref?.();
+        try {
+            for (;;) {
+                while (queue.length) {
+                    const chunk = queue.shift();
+                    yield chunk;
+                    if (cap != null && bytes > cap) {
+                        finished = true;
+                        kill();
+                        throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
+                    }
+                }
+                if (failure)
+                    throw failure;
+                if (finished)
+                    break;
+                const waitMs = idleMs != null ? Math.max(1, idleMs - (Date.now() - lastChunk)) : 30_000;
+                await new Promise((r) => { wake = r; setTimeout(r, waitMs); });
+                if (idleMs != null && !finished && Date.now() - lastChunk >= idleMs) {
+                    finished = true;
+                    kill();
+                    throw new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (command hang)`);
+                }
+            }
+            while (queue.length)
+                yield queue.shift();
+            if (failure)
+                throw failure;
+            yield { type: "exit", exitCode };
+        }
+        finally {
+            if (!finished) {
+                finished = true;
+                kill();
+            }
+            if (wallTimer)
+                clearTimeout(wallTimer);
+            options?.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    async absolutePath(p) {
+        return ok(this.resolve(p));
+    }
+    async joinPath(parts) {
+        return ok(path.join(...parts));
+    }
+    async readTextFile(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            return ok(await fs.readFile(abs, { encoding: "utf8", signal: abortSignal }));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async readTextLines(p, options) {
+        const r = await this.readTextFile(p, options?.abortSignal);
+        if (!r.ok)
+            return r;
+        let lines = r.value.split(/\r?\n/);
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        if (options?.maxLines != null)
+            lines = lines.slice(0, options.maxLines);
+        return ok(lines);
+    }
+    async readBinaryFile(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            const buf = await fs.readFile(abs, { signal: abortSignal });
+            return ok(new Uint8Array(buf));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async writeFile(p, content, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            const data = typeof content === "string" ? content : Buffer.from(content);
+            await fs.writeFile(abs, data, { signal: abortSignal });
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async appendFile(p, content, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            if (abortSignal?.aborted)
+                throw Object.assign(new Error("aborted"), { name: "AbortError" });
+            const data = typeof content === "string" ? content : Buffer.from(content);
+            await fs.appendFile(abs, data);
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async fileInfo(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            const st = await fs.lstat(abs);
+            return ok({
+                name: path.basename(abs),
+                path: abs,
+                kind: st.isDirectory() ? "directory" : st.isSymbolicLink() ? "symlink" : "file",
+                size: st.size,
+                mtimeMs: st.mtimeMs,
+            });
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async listDir(p, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            const entries = await fs.readdir(abs, { withFileTypes: true });
+            const out = [];
+            for (const e of entries) {
+                const child = path.join(abs, e.name);
+                let size = 0;
+                let mtimeMs = 0;
+                try {
+                    const st = await fs.lstat(child);
+                    size = st.size;
+                    mtimeMs = st.mtimeMs;
+                }
+                catch {
+                }
+                out.push({ name: e.name, path: child, kind: kindFromDirent(e), size, mtimeMs });
+            }
+            return ok(out);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async canonicalPath(p, abortSignal) {
+        const abs = this.resolve(p);
+        try {
+            return ok(await fs.realpath(abs));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async readLink(p, abortSignal) {
+        const abs = this.resolve(p);
+        try {
+            return ok(await fs.readlink(abs));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, abortSignal) };
+        }
+    }
+    async exists(p, abortSignal) {
+        const abs = this.resolve(p);
+        try {
+            await fs.lstat(abs);
+            return ok(true);
+        }
+        catch (e) {
+            const fe = this.fileError(e, abs, abortSignal);
+            if (fe.code === "not_found")
+                return ok(false);
+            return { ok: false, error: fe };
+        }
+    }
+    async createDir(p, options) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            await fs.mkdir(abs, { recursive: options?.recursive ?? true });
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
+        }
+    }
+    async remove(p, options) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
+        const abs = this.resolve(p);
+        try {
+            if (!options?.force) {
+                await fs.lstat(abs);
+            }
+            await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
+            return ok(undefined);
+        }
+        catch (e) {
+            const fe = this.fileError(e, abs, options?.abortSignal);
+            if (options?.force && fe.code === "not_found")
+                return ok(undefined);
+            return { ok: false, error: fe };
+        }
+    }
+    async createTempDir(prefix = "tmp-", abortSignal) {
+        const ready = await this.fsReady(".");
+        if (!ready.ok)
+            return ready;
+        try {
+            return ok(await fs.mkdtemp(path.join(this.workspaceDir, prefix)));
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
+        }
+    }
+    async createTempFile(options) {
+        const ready = await this.fsReady(".");
+        if (!ready.ok)
+            return ready;
+        const prefix = options?.prefix ?? "";
+        const suffix = options?.suffix ?? "";
+        try {
+            const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
+            const abs = path.join(this.workspaceDir, name);
+            if (options?.abortSignal?.aborted)
+                throw Object.assign(new Error("aborted"), { name: "AbortError" });
+            await fs.writeFile(abs, "", { flag: "wx" });
+            return ok(abs);
+        }
+        catch (e) {
+            return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
+        }
+    }
+    resolve(p) {
+        return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
+    }
+    ensurePrepared() {
+        if (this.prepared)
+            return Promise.resolve();
+        if (!this.preparing) {
+            this.preparing = fs
+                .mkdir(this.workspaceDir, { recursive: true })
+                .then(() => {
+                this.prepared = true;
+            })
+                .catch((e) => {
+                this.preparing = undefined;
+                throw e;
+            });
+        }
+        return this.preparing;
+    }
+    async shellReady() {
+        if (this.destroyed)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
+        try {
+            try {
+                await resolveHostShell();
+            }
+            catch (e) {
+                return { ok: false, error: new ExecutionError("shell_unavailable", errMsg(e), asError(e)) };
+            }
+            await this.ensurePrepared();
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: new ExecutionError("shell_unavailable", `failed to create host workspace: ${errMsg(e)}`, asError(e)) };
+        }
+    }
+    async fsReady(p) {
+        if (this.destroyed)
+            return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
+        try {
+            await this.ensurePrepared();
+            return ok(undefined);
+        }
+        catch (e) {
+            return { ok: false, error: new FileError("unknown", `failed to create host workspace: ${errMsg(e)}`, this.resolve(p), asError(e)) };
+        }
+    }
+    inheritMode() {
+        if (this.cfg.inheritEnv !== undefined)
+            return this.cfg.inheritEnv;
+        if (this.cfg.inheritProcessEnv === false)
+            return [];
+        if (this.cfg.inheritProcessEnv === true)
+            return "all";
+        return "scrub";
+    }
+    mergeEnv(perCommand) {
+        const mode = this.inheritMode();
+        let base;
+        if (mode === "all")
+            base = { ...process.env };
+        else if (Array.isArray(mode)) {
+            base = {};
+            for (const k of mode)
+                if (process.env[k] !== undefined)
+                    base[k] = process.env[k];
+        }
+        else
+            base = scrubSecretEnv(process.env);
+        if (this.cfg.env)
+            Object.assign(base, this.cfg.env);
+        if (perCommand)
+            Object.assign(base, perCommand);
+        if (process.platform === "win32")
+            base.SHELL = hostShell().shell;
+        return collapseWin32EnvKeys(base);
+    }
+    fileError(e, p, abortSignal) {
+        if (e instanceof FileError)
+            return e;
+        const msg = errMsg(e);
+        const name = e?.name;
+        if (abortSignal?.aborted || name === "AbortError")
+            return new FileError("aborted", msg, p);
+        const code = e?.code;
+        if (code === "ENOENT")
+            return new FileError("not_found", msg, p);
+        if (code === "EACCES" || code === "EPERM")
+            return new FileError("permission_denied", msg, p);
+        if (code === "EISDIR")
+            return new FileError("is_directory", msg, p);
+        if (code === "ENOTDIR")
+            return new FileError("not_directory", msg, p);
+        if (code === "EINVAL")
+            return new FileError("invalid", msg, p);
+        return new FileError("unknown", msg, p);
+    }
+}
+function sanitizeId(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64) || "task";
+}
+function kindFromDirent(e) {
+    if (e.isSymbolicLink())
+        return "symlink";
+    if (e.isDirectory())
+        return "directory";
+    return "file";
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function asError(e) {
+    return e instanceof Error ? e : undefined;
+}
+function signalNumber(signal) {
+    return os.constants.signals[signal];
+}
+export function hostExecutionEnvFactory(config = {}) {
+    return (ctx) => new RemoteHostExecutionEnv({
+        ...config,
+        id: config.id ?? ctx.taskId ?? ctx.sessionId,
+    });
+}
+export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
+export function remoteDockerExecutionEnvFactory(_config) {
+    throw new RemoteExecutionError("unsupported", "remoteExec provider 'remote-docker' is not yet implemented (DUAL-MODE-DESIGN §5 fast-follow) — use 'host', 'local-docker', or 'e2b' until it ships");
+}
+//# sourceMappingURL=remote-env-host.js.map