@gpzhang2001/sharpkit-sandbox 0.2.1

package/lib/index.js

@@ -0,0 +1,1145 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+//#region src/caido.ts
+/** Exact login mutation body strix posts (caido_bootstrap.py `_LOGIN_AS_GUEST_BODY`). */
+const LOGIN_AS_GUEST_QUERY = "mutation LoginAsGuest { loginAsGuest { token { accessToken } } }";
+/** Minimal CreateProject mutation (error identified by typename only — the
+* payload error union has no shared `code` field in Caido 0.56.0's schema). */
+const CREATE_PROJECT_DOC = "mutation CreateProject($input: CreateProjectInput!) { createProject(input: $input) { error { __typename } project { id name temporary } } }";
+/** Minimal SelectProject mutation (typename-only error, same schema reason). */
+const SELECT_PROJECT_DOC = "mutation SelectProject($id: ID!) { selectProject(id: $id) { currentProject { project { id } } error { __typename } } }";
+/** Project identity strix creates in every sandbox (protocol constant, not a tunable). */
+const PROJECT_NAME = "sandbox";
+/**
+* Build the container-internal curl login command (strix caido_bootstrap.py:46-57).
+* @param containerBaseUrl - the in-container Caido base URL (`http://127.0.0.1:48080`).
+* @returns the shell command string for exec.
+*/
+function loginCurlCommand(containerBaseUrl) {
+	const body = JSON.stringify({ query: LOGIN_AS_GUEST_QUERY });
+	return `curl -fsS -X POST -H "Content-Type: application/json" -d ${JSON.stringify(body)} ${containerBaseUrl}/graphql`;
+}
+/**
+* Extract the guest token from a login response payload.
+* @param stdout - raw curl stdout.
+* @returns the access token.
+* @throws when the payload is unparseable or carries no token (strix error wording).
+*/
+function parseLoginToken(stdout) {
+	let payload;
+	try {
+		payload = JSON.parse(stdout);
+	} catch (error) {
+		throw new Error(`unparseable response: ${String(error)}: '${stdout}'`);
+	}
+	const token = pathOf(payload, [
+		"data",
+		"loginAsGuest",
+		"token",
+		"accessToken"
+	]);
+	if (typeof token !== "string" || token === "") throw new Error(`loginAsGuest returned no token: ${JSON.stringify(payload)}`);
+	return token;
+}
+/** Best-effort nested property lookup on an unknown JSON value. */
+function pathOf(value, path) {
+	let current = value;
+	for (const key of path) {
+		if (typeof current !== "object" || current === null) return void 0;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* Run the guest login with retries (strix `_login_as_guest`: attempts with
+* capped linear backoff 2,4,6,8,8… seconds; per-attempt exec timeout).
+* @param exec - container exec channel.
+* @param containerBaseUrl - in-container Caido base URL.
+* @param options - attempts/timeout/backoff knobs and injected sleep.
+* @returns the access token.
+* @throws when every attempt fails (strix error wording).
+*/
+async function loginAsGuest(exec, containerBaseUrl, options) {
+	const command = loginCurlCommand(containerBaseUrl);
+	let lastError = "no attempt made";
+	for (let attempt = 1; attempt <= options.attempts; attempt++) {
+		try {
+			const result = await exec(command, options.timeoutMs);
+			if (result.ok) return parseLoginToken(result.stdout);
+			lastError = `curl exit ${result.exitCode === null ? "unknown" : result.exitCode}: ${result.stderr.slice(0, 200)}`;
+		} catch (error) {
+			lastError = String(error instanceof Error ? error.message : error);
+		}
+		if (attempt < options.attempts) await options.sleep(Math.min(2e3 * attempt, 8e3));
+	}
+	throw new Error(`loginAsGuest failed after ${options.attempts} attempts: ${lastError}`);
+}
+/**
+* POST one GraphQL document with bearer auth and return the `data` object.
+* @param fetchFn - fetch channel.
+* @param baseUrl - host-side Caido base URL.
+* @param token - bearer token.
+* @param doc - the GraphQL document.
+* @param variables - operation variables.
+* @param signal - cancellation for teardown.
+*/
+async function graphql(fetchFn, baseUrl, token, doc, variables, signal) {
+	const response = await fetchFn(`${baseUrl}/graphql`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${token}`
+		},
+		body: JSON.stringify({
+			query: doc,
+			variables
+		}),
+		signal
+	});
+	const text = await response.text();
+	if (response.status !== 200) throw new Error(`caido graphql HTTP ${response.status}: ${text.slice(0, 200)}`);
+	let payload;
+	try {
+		payload = JSON.parse(text);
+	} catch (error) {
+		throw new Error(`caido graphql unparseable response: ${String(error)}`);
+	}
+	const data = pathOf(payload, ["data"]);
+	if (typeof data !== "object" || data === null) {
+		const errors = pathOf(payload, ["errors"]);
+		const detail = Array.isArray(errors) ? JSON.stringify(errors).slice(0, 300) : text.slice(0, 200);
+		throw new Error(`caido graphql carried no data: ${detail}`);
+	}
+	return data;
+}
+/** Extract the sibling error of an operation result, for error messages. */
+function errorOf(entry) {
+	if (typeof entry !== "object" || entry === null) return void 0;
+	const error = entry["error"];
+	if (typeof error !== "object" || error === null) return void 0;
+	return error;
+}
+/**
+* Full bootstrap: guest login, then create the temporary sandbox project and
+* select it (strix `bootstrap_caido`).
+* @param exec - container exec channel (login curl runs in-container).
+* @param fetchFn - host-side fetch channel (project calls).
+* @param urls - container and host base URLs.
+* @param options - retry/timeout knobs and injected sleep.
+* @returns the ready endpoint.
+*/
+async function bootstrapCaido(exec, fetchFn, urls, options) {
+	const token = await loginAsGuest(exec, urls.containerBaseUrl, options);
+	const createData = await graphql(fetchFn, urls.hostBaseUrl, token, CREATE_PROJECT_DOC, { input: {
+		name: PROJECT_NAME,
+		temporary: true
+	} }, options.signal);
+	const createError = errorOf(createData["createProject"]);
+	if (createError !== void 0) throw new Error(`createProject failed: ${createError.__typename}${createError.code === void 0 ? "" : ` (${createError.code})`}`);
+	const projectId = pathOf(createData["createProject"], ["project", "id"]);
+	if (typeof projectId !== "string" || projectId === "") throw new Error("createProject returned no project id");
+	const selectError = errorOf((await graphql(fetchFn, urls.hostBaseUrl, token, SELECT_PROJECT_DOC, { id: projectId }, options.signal))["selectProject"]);
+	if (selectError !== void 0) throw new Error(`selectProject failed: ${selectError.__typename}${selectError.code === void 0 ? "" : ` (${selectError.code})`}`);
+	return {
+		baseUrl: urls.hostBaseUrl,
+		token,
+		projectId
+	};
+}
+/**
+* Shared, lazily-resolved bootstrap task (strix `CaidoBootstrapHandle`): the
+* promise is created once and shared, so individual consumer cancellations
+* cannot cancel the shared bootstrap; `close()` aborts it for teardown.
+*/
+var CaidoBootstrap = class {
+	endpoint;
+	controller = new AbortController();
+	settled;
+	constructor(start) {
+		this.endpoint = start(this.controller.signal).then((endpoint) => {
+			this.settled = endpoint;
+			return endpoint;
+		}, (error) => {
+			throw error;
+		});
+		this.endpoint.catch(() => {});
+	}
+	/** Resolve the endpoint; rejects with the bootstrap failure, shared by all callers. */
+	get() {
+		return this.endpoint;
+	}
+	/** The resolved endpoint, or undefined while pending/failed (strix `peek`). */
+	peek() {
+		return this.settled;
+	}
+	/** Abort a pending bootstrap; failures are swallowed (teardown path). */
+	close() {
+		this.controller.abort();
+	}
+};
+//#endregion
+//#region src/mounts.ts
+/** Metadata names that get their own read-only overlay mount. */
+const PROTECTED_METADATA_NAMES = [
+	".git",
+	".agents",
+	".codex"
+];
+/**
+* Whether `child` is `parent` itself or underneath it, POSIX-style.
+* @param parent - candidate ancestor path, already canonical.
+* @param child - candidate descendant path, already canonical.
+*/
+function isSubpath(parent, child) {
+	return child === parent || child.startsWith(`${parent}/`);
+}
+/**
+* Parse a git worktree `.git` pointer file for its `gitdir:` line.
+* @param content - the raw pointer file text.
+* @param base - directory of the pointer file, for relative gitdir values.
+* @param resolve - canonicalizer for the candidate path.
+* @returns the resolved gitdir, or null when absent/malformed.
+*/
+function parseGitdirPointer(content, base, resolve) {
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trimEnd();
+		const separator = line.indexOf(":");
+		if (separator === -1) continue;
+		if (line.slice(0, separator).trim() !== "gitdir") continue;
+		const value = line.slice(separator + 1).trim();
+		if (value === "") continue;
+		return resolve(value.startsWith("/") ? value : `${base}/${value}`);
+	}
+	return null;
+}
+/**
+* Build the read-only metadata overlay mounts for one source tree (strix
+* `_metadata_mounts`): each protected name that exists in the tree is mounted
+* read-only at `<target>/<name>`; a file-shaped `.git` (worktree pointer)
+* additionally gets its resolved gitdir mounted read-only when the gitdir
+* stays inside the tree.
+* @param tree - canonical host path of the source tree.
+* @param target - container mount target of the tree (e.g. `/workspace/app`).
+* @param probe - filesystem facts.
+* @returns the overlay mounts (possibly empty).
+*/
+function metadataMounts(tree, target, probe) {
+	const mounts = [];
+	for (const name of PROTECTED_METADATA_NAMES) {
+		const path = `${tree}/${name}`;
+		if (!probe.exists(path)) continue;
+		const isDir = probe.isDirectory(path);
+		if (!isDir && !probe.isFile(path)) continue;
+		const resolved = probe.resolve(path);
+		if (!isSubpath(tree, resolved)) continue;
+		mounts.push({
+			source: resolved,
+			target: `${target}/${name}`,
+			readOnly: true
+		});
+		if (!isDir) {
+			const content = probe.readTextFile(path);
+			if (content === null) continue;
+			const gitdir = parseGitdirPointer(content, path.substring(0, path.lastIndexOf("/")), probe.resolve);
+			if (gitdir === null || !probe.exists(gitdir) || !isSubpath(tree, gitdir)) continue;
+			const relative = gitdir.slice(tree.length + 1);
+			mounts.push({
+				source: gitdir,
+				target: `${target}/${relative}`,
+				readOnly: true
+			});
+		}
+	}
+	return mounts;
+}
+/**
+* Build every bind mount for the session's sources: workspace mounts plus
+* metadata overlays, sorted shallowest-target-first so nested targets land on
+* top (strix sort by `/` count).
+* @param sources - the source specs; entries missing either path part are skipped.
+* @param probe - filesystem facts.
+* @param workspaceRoot - container workspace root (default `/workspace`).
+* @returns the sorted mounts.
+*/
+function buildBindMounts(sources, probe, workspaceRoot) {
+	const mounts = [];
+	for (const source of sources) {
+		if (source.workspaceSubdir === "" || source.sourcePath === "") continue;
+		const resolved = probe.resolve(source.sourcePath);
+		const target = `${workspaceRoot}/${source.workspaceSubdir}`;
+		mounts.push({
+			source: resolved,
+			target,
+			readOnly: false
+		});
+		if (source.protectMetadata === true) mounts.push(...metadataMounts(resolved, target, probe));
+	}
+	return mounts.sort((a, b) => targetDepth(a.target) - targetDepth(b.target) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+}
+/** Path depth = number of `/` separators (strix ordering metric). */
+function targetDepth(target) {
+	let depth = 0;
+	for (const char of target) if (char === "/") depth++;
+	return depth;
+}
+/**
+* Validate an extra file's container path (strix `_extra_file_rel_path`):
+* must live under the workspace root, have no empty/`.`/`..` segments, and
+* carry no control characters.
+* @param containerPath - the requested absolute container path.
+* @param workspaceRoot - container workspace root (default `/workspace`).
+* @returns the workspace-relative path, or null when invalid.
+*/
+function extraFileRelPath(containerPath, workspaceRoot) {
+	const prefix = `${workspaceRoot}/`;
+	if (!containerPath.startsWith(prefix)) return null;
+	const rel = containerPath.slice(prefix.length).replace(/^\/+/, "");
+	if (rel === "") return null;
+	const segments = rel.split("/");
+	for (const segment of segments) {
+		if (segment === "" || segment === "." || segment === "..") return null;
+		for (const char of segment) {
+			const code = char.codePointAt(0);
+			if (code === void 0 || code < 32 || code === 127) return null;
+		}
+	}
+	return rel;
+}
+/**
+* Whether a candidate workspace-relative path collides with any source root
+* or previously placed extra file (strix `_collides_with_source_root`,
+* ancestor relationships included).
+* @param rel - candidate workspace-relative path.
+* @param roots - existing roots (subdirs and placed extra files), workspace-relative.
+*/
+function collidesWithRoots(rel, roots) {
+	return roots.some((root) => rel === root || rel.startsWith(`${root}/`) || root.startsWith(`${rel}/`));
+}
+/**
+* Sanitize a scan id for a staging directory name (strix keeps `[alnum]-_.`,
+* everything else becomes `-`).
+* @param scanId - the raw scan id.
+* @returns the sanitized name fragment (empty collapses to a single `-`).
+*/
+function stagingDirName(scanId) {
+	let safe = "";
+	for (const char of scanId) safe += /[A-Za-z0-9]/.test(char) || char === "-" || char === "_" || char === "." ? char : "-";
+	return safe === "" ? "-" : safe;
+}
+//#endregion
+//#region src/spec.ts
+/** Values that disable the json-file log rotation opts (strix `_apply_log_limits`). */
+const LOG_DISABLED_SIZES = /* @__PURE__ */ new Set([
+	"0",
+	"off",
+	"none",
+	"unlimited"
+]);
+/**
+* Build the `docker create` argv for a sandbox spec. Env/hosts/labels are
+* emitted in sorted-key order for deterministic tests; mounts keep their
+* (pre-sorted) order.
+* @param spec - the assembled create spec.
+* @returns the full argv, `["docker","create",…flags,image,…command]`.
+*/
+function buildCreateArgv(spec) {
+	const argv = ["docker", "create"];
+	for (const cap of spec.caps ?? []) argv.push("--cap-add", cap);
+	for (const key of Object.keys(spec.extraHosts ?? {}).sort()) argv.push("--add-host", `${key}=${spec.extraHosts?.[key]}`);
+	for (const key of Object.keys(spec.env).sort()) argv.push("-e", `${key}=${spec.env[key]}`);
+	for (const mount of spec.bindMounts) argv.push("-v", mount.readOnly ? `${mount.source}:${mount.target}:ro` : `${mount.source}:${mount.target}`);
+	if (spec.network !== void 0 && spec.network !== "") argv.push("--network", spec.network);
+	else argv.push("-p", `127.0.0.1::${spec.caidoPort}`);
+	const limits = spec.resourceLimits;
+	if (limits?.memLimit !== void 0 && limits.memLimit !== "") argv.push("--memory", limits.memLimit);
+	if (limits?.shmSize !== void 0 && limits.shmSize !== "") argv.push("--shm-size", limits.shmSize);
+	if (limits?.cpus !== void 0 && limits.cpus > 0) argv.push("--cpus", String(limits.cpus));
+	if (limits?.pidsLimit !== void 0 && Number.isInteger(limits.pidsLimit) && limits.pidsLimit > 0) argv.push("--pids-limit", String(limits.pidsLimit));
+	if (logRotationEnabled(spec.logMaxSize)) argv.push("--log-driver", "json-file", "--log-opt", `max-size=${spec.logMaxSize}`, "--log-opt", `max-file=${spec.logMaxFile ?? 3}`);
+	for (const key of Object.keys(spec.labels ?? {}).sort()) argv.push("--label", `${key}=${spec.labels?.[key]}`);
+	argv.push(spec.image, ...spec.command);
+	return argv;
+}
+/**
+* Whether json-file rotation opts should be emitted for a max-size value.
+* @param logMaxSize - the configured max-size; absent disables (docker default, unbounded).
+* @returns true when rotation opts must be emitted.
+*/
+function logRotationEnabled(logMaxSize) {
+	return logMaxSize !== void 0 && logMaxSize !== "" && !LOG_DISABLED_SIZES.has(logMaxSize.toLowerCase());
+}
+/**
+* Build the container environment (strix session_manager.py:316-329 parity).
+* Proxy vars point at the in-container Caido so all container HTTP traffic is
+* interceptable; NO_PROXY keeps CDP/localhost traffic out of the proxy.
+* @param options - ports/identity inputs; uid/gid only on Linux (ownership remap).
+* @returns the env record in stable insertion order.
+*/
+function buildContainerEnv(options) {
+	const proxy = `http://127.0.0.1:${options.caidoPort}`;
+	const env = {
+		PYTHONUNBUFFERED: "1",
+		HOST_GATEWAY: "host.docker.internal",
+		http_proxy: proxy,
+		https_proxy: proxy,
+		ALL_PROXY: proxy,
+		NO_PROXY: "localhost,127.0.0.1"
+	};
+	if (options.platform === "linux" && options.uid !== void 0 && options.uid > 0) {
+		env.SHARPKIT_HOST_UID = String(options.uid);
+		env.SHARPKIT_HOST_GID = String(options.gid ?? options.uid);
+	}
+	return env;
+}
+/**
+* Build the non-interactive exec argv: a fresh login shell per call
+* (`bash -lc`), matching the S1 spike and the image's login-shell PATH fixups.
+*/
+function buildExecArgv(options) {
+	const argv = [
+		"docker",
+		"exec",
+		"-i"
+	];
+	if (options.cwd !== void 0) argv.push("-w", options.cwd);
+	argv.push(options.containerId, "bash", "-lc", options.command);
+	return argv;
+}
+/**
+* Build the PTY exec argv (`docker exec -it`); the host-side PTY is provided
+* by `ctx.subprocess.spawnTerminal` and Ctrl-C is delivered as `\x03`
+* (spike finding D1.1).
+*/
+function buildExecTtyArgv(options) {
+	const argv = [
+		"docker",
+		"exec",
+		"-it"
+	];
+	if (options.cwd !== void 0) argv.push("-w", options.cwd);
+	argv.push(options.containerId, "bash", "-lc", options.command);
+	return argv;
+}
+/**
+* Build the argv resolving a published port's host endpoint (`docker port`).
+*/
+function buildPortArgv(containerId, port) {
+	return [
+		"docker",
+		"port",
+		containerId,
+		String(port)
+	];
+}
+/**
+* Parse `docker port` output into endpoints, preferring IPv4 (strix publishes
+* to 127.0.0.1). IPv6 literals arrive bracketed and are returned bracket-free
+* with `bracketedIPv6` only when the raw host contains `:`.
+* @param output - the raw `docker port` stdout (zero or more lines).
+* @returns endpoints, IPv4 entries first; empty when nothing is published.
+*/
+function parsePortOutput(output) {
+	const endpoints = [];
+	for (const rawLine of output.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "") continue;
+		const lastColon = line.lastIndexOf(":");
+		if (lastColon === -1) continue;
+		const port = Number.parseInt(line.slice(lastColon + 1), 10);
+		if (!Number.isInteger(port) || port <= 0 || port > 65535) continue;
+		let host = line.slice(0, lastColon);
+		if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+		if (host === "") continue;
+		endpoints.push({
+			host,
+			port
+		});
+	}
+	const preferred = endpoints.filter((endpoint) => !endpoint.host.includes(":"));
+	const ipv6 = endpoints.filter((endpoint) => endpoint.host.includes(":"));
+	return [...preferred, ...ipv6];
+}
+/**
+* Build the argv resolving the container's IP on a sandbox network (strix
+* `StrixDockerSandboxSession._resolve_exposed_port`, network mode).
+*/
+function buildNetworkIpArgv(containerId, network) {
+	return [
+		"docker",
+		"inspect",
+		"--format",
+		`{{.NetworkSettings.Networks.${network}.IPAddress}}`,
+		containerId
+	];
+}
+/** Container-side path reference for `docker cp` (`<id>:<path>`). */
+function containerRef(containerId, containerPath) {
+	return `${containerId}:${containerPath}`;
+}
+/** Build the `docker cp` argv copying a host file into the container. */
+function buildPutFileArgv(hostPath, containerId, containerPath) {
+	return [
+		"docker",
+		"cp",
+		hostPath,
+		containerRef(containerId, containerPath)
+	];
+}
+/** Build the `docker cp` argv copying a container file out to a host path. */
+function buildGetFileArgv(containerId, containerPath, hostPath) {
+	return [
+		"docker",
+		"cp",
+		containerRef(containerId, containerPath),
+		hostPath
+	];
+}
+/** Build the graceful stop argv (`docker stop -t <seconds>`). */
+function buildStopArgv(containerId, graceMs) {
+	const seconds = Math.max(0, Math.round(graceMs / 1e3));
+	return [
+		"docker",
+		"stop",
+		"-t",
+		String(seconds),
+		containerId
+	];
+}
+/** Build the plain remove argv; the caller escalates to force-remove on failure. */
+function buildRmArgv(containerId) {
+	return [
+		"docker",
+		"rm",
+		containerId
+	];
+}
+/** Build the force-remove argv (fallback path and failure cleanup). */
+function buildRmForceArgv(containerId) {
+	return [
+		"docker",
+		"rm",
+		"-f",
+		containerId
+	];
+}
+/** Build the argv checking whether an image is present locally. */
+function buildImageInspectArgv(image) {
+	return [
+		"docker",
+		"image",
+		"inspect",
+		image
+	];
+}
+/** Build the pull argv (strix pulls only when the image is missing). */
+function buildPullArgv(image) {
+	return [
+		"docker",
+		"pull",
+		image
+	];
+}
+/** Build the start argv. */
+function buildStartArgv(containerId) {
+	return [
+		"docker",
+		"start",
+		containerId
+	];
+}
+//#endregion
+//#region src/brand.ts
+/** Brand a raw string as a {@link SandboxSessionId}. */
+function SandboxSessionId(id) {
+	return id;
+}
+/** Brand a raw string as a {@link SandboxProcessId}. */
+function SandboxProcessId(id) {
+	return id;
+}
+//#endregion
+//#region src/session.ts
+/**
+* One docker-CLI sandbox session: exec/PTY command execution, file transfer
+* via `docker cp`, lazy Caido endpoint, and strix-parity teardown. The
+* subprocess seam arrives as a structural interface so the session is
+* drivable from tests exactly like the S1 spike drove it. Teardown follows
+* strix session_manager.cleanup order (staging → caido → container), each
+* step best-effort with logging; host-side PTY trees are terminated first
+* (spike finding D1.4: host terminate cannot reach daemon-owned container
+* processes, so `docker rm -f` is the authoritative reaper).
+* @module @gpzhang2001/sharpkit-sandbox/session
+*/
+/** Collected output read helper: reader text or ''. */
+function readerText(handle, stream) {
+	return handle.collected[stream]?.readFrom(0).text ?? "";
+}
+/**
+* Run one argv to completion with collected output and a hard timeout that
+* terminates (and joins) the tree — the primitive every docker CLI call in
+* the session goes through. A timeout and a caller abort terminate the host
+* tree identically but are reported separately (`timedOut` vs `aborted`);
+* per spike finding D1.4, host-side termination cannot reach daemon-owned
+* container processes — a timed-out `docker exec` may leave its command
+* running inside the container until the session stops and reaps it.
+* @param subprocess - the subprocess seam.
+* @param argv - full argv, argv[0] a program (never shell-interpreted).
+* @param options - timeout and terminate grace.
+* @returns the collected outcome.
+*/
+async function runCollectArgv(subprocess, argv, options) {
+	const handle = subprocess.spawn({
+		argv,
+		cwd: process.cwd(),
+		stdio: {
+			stdin: "ignore",
+			stdout: { maxBytes: options.collectMaxBytes },
+			stderr: { maxBytes: options.collectMaxBytes }
+		},
+		graceMs: options.graceMs
+	});
+	let timedOut = false;
+	let aborted = false;
+	let timer;
+	let onAbort;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			timedOut = true;
+			handle.terminate();
+			resolve("deadline");
+		}, options.timeoutMs);
+		const signal = options.signal;
+		if (signal !== void 0) {
+			onAbort = () => {
+				aborted = true;
+				handle.terminate();
+				resolve("deadline");
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+	const winner = await Promise.race([handle.done.then((outcome) => ({ outcome })), deadline.then(() => "deadline")]);
+	if (timer !== void 0) clearTimeout(timer);
+	if (onAbort !== void 0) options.signal?.removeEventListener("abort", onAbort);
+	const outcome = winner === "deadline" ? await handle.done : winner.outcome;
+	return {
+		exitCode: outcome.exitCode,
+		signal: outcome.signal,
+		stdout: readerText(handle, "stdout"),
+		stderr: readerText(handle, "stderr"),
+		timedOut,
+		aborted
+	};
+}
+/**
+* The docker-CLI-backed {@link PentestSandboxSession}. Constructed by the
+* service after the container is created and started; never constructed
+* directly by consumers.
+*/
+var DockerCliSandboxSession = class {
+	sessionId;
+	scanId;
+	containerId;
+	deps;
+	ttyProcesses = /* @__PURE__ */ new Map();
+	stopped = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.sessionId = crypto.randomUUID();
+		this.scanId = deps.scanId;
+		this.containerId = deps.containerId;
+	}
+	async ready() {
+		await this.deps.bootstrap.get();
+	}
+	async caidoEndpoint() {
+		return this.deps.bootstrap.get();
+	}
+	async exec(command, options) {
+		if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`);
+		const timeoutMs = options?.timeoutMs ?? this.deps.defaultExecTimeoutMs;
+		return runCollectArgv(this.deps.subprocess, buildExecArgv({
+			containerId: this.containerId,
+			command,
+			cwd: options?.cwd
+		}), {
+			timeoutMs,
+			graceMs: this.deps.graceMs,
+			collectMaxBytes: this.deps.collectMaxBytes,
+			signal: options?.signal
+		});
+	}
+	/**
+	* Start a cancellable long-running exec with no timeout (jobs own the
+	* lifetime): the caller polls {@link SandboxExecProcess.readOutput} deltas
+	* and terminates on cancel.
+	*/
+	execJob(command, options) {
+		if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`);
+		const handle = this.deps.subprocess.spawn({
+			argv: buildExecArgv({
+				containerId: this.containerId,
+				command,
+				cwd: options?.cwd
+			}),
+			cwd: process.cwd(),
+			stdio: {
+				stdin: "ignore",
+				stdout: { maxBytes: this.deps.collectMaxBytes },
+				stderr: { maxBytes: this.deps.collectMaxBytes }
+			},
+			graceMs: this.deps.graceMs
+		});
+		let offset = 0;
+		return {
+			processId: SandboxProcessId(crypto.randomUUID()),
+			done: handle.done.then((outcome) => {
+				const stdout = handle.collected.stdout?.readFrom(0).text ?? "";
+				const stderr = handle.collected.stderr?.readFrom(0).text ?? "";
+				return {
+					exitCode: outcome.exitCode,
+					signal: outcome.signal,
+					stdout,
+					stderr,
+					timedOut: false,
+					aborted: false
+				};
+			}),
+			readOutput: () => {
+				const read = handle.collected.stdout?.readFrom(offset);
+				if (read === void 0) return "";
+				offset = read.nextOffset;
+				return read.text;
+			},
+			terminate: () => {
+				handle.terminate();
+			}
+		};
+	}
+	async execTty(command, options) {
+		if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`);
+		const handle = await this.deps.subprocess.spawnTerminal({
+			argv: buildExecTtyArgv({
+				containerId: this.containerId,
+				command,
+				cwd: options?.cwd
+			}),
+			cwd: process.cwd(),
+			rows: options?.rows ?? 24,
+			cols: options?.cols ?? 80,
+			graceMs: this.deps.graceMs
+		});
+		const id = SandboxProcessId(crypto.randomUUID());
+		const listeners = /* @__PURE__ */ new Set();
+		const decoder = new TextDecoder();
+		handle.output.on("data", (chunk) => {
+			const text = decoder.decode(chunk, { stream: true });
+			for (const listener of listeners) listener(text);
+		});
+		const done = handle.done.then((outcome) => ({
+			exitCode: outcome.exitCode,
+			signal: outcome.signal,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			aborted: false
+		}));
+		const record = {
+			handle,
+			listeners,
+			process: {
+				id,
+				command,
+				write: (chars) => handle.write(chars),
+				subscribe: (listener) => {
+					listeners.add(listener);
+					return () => {
+						listeners.delete(listener);
+					};
+				},
+				done,
+				terminate: () => handle.terminate()
+			}
+		};
+		this.ttyProcesses.set(id, record);
+		done.then(() => {
+			this.ttyProcesses.delete(id);
+		}, () => {
+			this.ttyProcesses.delete(id);
+		});
+		return record.process;
+	}
+	async writeStdin(processId, chars) {
+		const record = this.ttyProcesses.get(processId);
+		if (record === void 0) throw new Error(`write_stdin: no live interactive process ${processId} in scan ${this.scanId}`);
+		await record.handle.write(chars);
+	}
+	async putFile(hostPath, containerPath) {
+		const result = await runCollectArgv(this.deps.subprocess, buildPutFileArgv(hostPath, this.containerId, containerPath), {
+			timeoutMs: this.deps.defaultExecTimeoutMs,
+			graceMs: this.deps.graceMs,
+			collectMaxBytes: this.deps.collectMaxBytes
+		});
+		if (result.exitCode !== 0) throw new Error(`putFile failed (exit ${result.exitCode}): ${result.stderr.slice(0, 500)}`);
+	}
+	async getFile(containerPath) {
+		const name = basename(containerPath);
+		if (name === "" || name === "/" || name === ".") throw new Error(`getFile: container path must name a file: ${containerPath}`);
+		const dir = await mkdtemp(join(tmpdir(), "sharpkit-getfile-"));
+		try {
+			const hostPath = join(dir, name);
+			const result = await runCollectArgv(this.deps.subprocess, buildGetFileArgv(this.containerId, containerPath, hostPath), {
+				timeoutMs: this.deps.defaultExecTimeoutMs,
+				graceMs: this.deps.graceMs,
+				collectMaxBytes: this.deps.collectMaxBytes
+			});
+			if (result.exitCode !== 0) throw new Error(`getFile failed (exit ${result.exitCode}): ${result.stderr.slice(0, 500)}`);
+			return new Uint8Array(await readFile(hostPath));
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		}
+	}
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		const log = this.deps.logger;
+		for (const record of this.ttyProcesses.values()) try {
+			await record.handle.terminate();
+		} catch (error) {
+			log.debug(`stop(${this.scanId}): tty terminate raised: ${String(error)}`);
+		}
+		this.ttyProcesses.clear();
+		if (this.deps.stagingDir !== void 0) await rm(this.deps.stagingDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+		this.deps.bootstrap.close();
+		try {
+			const stopped = await runCollectArgv(this.deps.subprocess, buildStopArgv(this.containerId, this.deps.graceMs), {
+				timeoutMs: this.deps.defaultExecTimeoutMs,
+				graceMs: this.deps.graceMs,
+				collectMaxBytes: this.deps.collectMaxBytes
+			});
+			if (stopped.exitCode !== 0) log.warn(`stop(${this.scanId}): docker stop exit ${stopped.exitCode}: ${stopped.stderr.slice(0, 200)}`);
+		} catch (error) {
+			log.debug(`stop(${this.scanId}): docker stop raised: ${String(error)}`);
+		}
+		try {
+			if ((await runCollectArgv(this.deps.subprocess, buildRmArgv(this.containerId), {
+				timeoutMs: this.deps.defaultExecTimeoutMs,
+				graceMs: this.deps.graceMs,
+				collectMaxBytes: this.deps.collectMaxBytes
+			})).exitCode !== 0) await runCollectArgv(this.deps.subprocess, buildRmForceArgv(this.containerId), {
+				timeoutMs: this.deps.defaultExecTimeoutMs,
+				graceMs: this.deps.graceMs,
+				collectMaxBytes: this.deps.collectMaxBytes
+			});
+		} catch (error) {
+			log.error(`stop(${this.scanId}): container removal raised; container may need manual reaping: ${String(error)}`);
+		}
+	}
+};
+/**
+* Stage extra files for bind mounting (strix `build_extra_file_bind_mounts`):
+* one numbered subdir per file, content written, mounted read-only at its
+* workspace path.
+* @param stagingDir - the session staging directory (already created).
+* @param items - validated extra files: rel path + bytes.
+* @param workspaceRoot - container workspace root (default `/workspace`).
+* @returns the mounts, in placement order.
+*/
+async function stageExtraFiles(stagingDir, items, workspaceRoot) {
+	const mounts = [];
+	let index = 0;
+	for (const item of items) {
+		const staged = join(stagingDir, String(index), basename(item.rel));
+		await mkdir(dirname(staged), { recursive: true });
+		await writeFile(staged, item.content);
+		mounts.push({
+			source: staged,
+			target: `${workspaceRoot}/${item.rel}`,
+			readOnly: true
+		});
+		index++;
+	}
+	return mounts;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Docker sandbox capability for the sharpkit pentest suite: the
+* `ctx.pentestSandbox` service (decision D1: `ctx.subprocess` + docker CLI,
+* argv built by the pure spec module). Port of strix runtime/session_manager
+* `create_or_reuse` + `cleanup` semantics: sessions cached by scan id,
+* container lifecycle over the CLI, extra files staged under the temp dir
+* (a remote docker daemon resolves bind sources on its own filesystem), and
+* a lazy Caido bootstrap that runs concurrently with scan start. Teardown is
+* registered once via ctx.effect and stops every live session best-effort.
+* @module @gpzhang2001/sharpkit-sandbox
+*/
+/** Container-side Caido port (protocol constant with the image, not a tunable). */
+const CAIDO_PORT = 48080;
+/** Keep-alive command (protocol with the image entrypoint, which execs it). */
+const KEEPALIVE_COMMAND = [
+	"tail",
+	"-f",
+	"/dev/null"
+];
+/**
+* The pentest sandbox service: creates, caches, and reuses docker-CLI
+* sandbox sessions. Load as a plugin after a subprocess provider; it
+* registers as `ctx.pentestSandbox` (one per context).
+*/
+var PentestSandboxService = class extends Service {
+	static inject = ["subprocess"];
+	static Config = z.object({
+		image: z.string().default("ghcr.io/gpzhang2001/sharpkit-sandbox:1.0.0-fork2"),
+		containerGraceMs: z.number().default(1e4),
+		workspaceRoot: z.string().default("/workspace"),
+		network: z.string(),
+		memLimit: z.string(),
+		shmSize: z.string(),
+		cpus: z.number(),
+		pidsLimit: z.number(),
+		logMaxSize: z.string().default("50m"),
+		logMaxFile: z.number().default(3),
+		runLabelId: z.string(),
+		runLabelType: z.string(),
+		caidoLoginAttempts: z.number().default(10),
+		caidoLoginTimeoutMs: z.number().default(15e3),
+		defaultExecTimeoutMs: z.number().default(12e4),
+		execCollectMaxBytes: z.number().default(1048576)
+	});
+	config;
+	sessions = /* @__PURE__ */ new Map();
+	/** node:fs-backed mount facts; a handful of sync calls on a few paths. */
+	probe = {
+		resolve: (path) => realpathSync(path.startsWith("~/") ? join(homedir(), path.slice(2)) : path),
+		exists: (path) => existsSync(path),
+		isDirectory: (path) => {
+			try {
+				return statSync(path).isDirectory();
+			} catch {
+				return false;
+			}
+		},
+		isFile: (path) => {
+			try {
+				return statSync(path).isFile();
+			} catch {
+				return false;
+			}
+		},
+		readTextFile: (path) => {
+			try {
+				return readFileSync(path, "utf8");
+			} catch {
+				return null;
+			}
+		}
+	};
+	constructor(ctx, config = {}) {
+		super(ctx, "pentestSandbox");
+		this.config = config;
+		ctx.effect(() => async () => {
+			for (const session of this.sessions.values()) await session.stop();
+			this.sessions.clear();
+		}, "pentest-sandbox session teardown");
+	}
+	/**
+	* Create (or reuse) the sandbox session for a scan id — strix
+	* `create_or_reuse` parity, including lazy Caido bootstrap.
+	* @param options - scan identity, sources, extra files.
+	* @returns the live session.
+	*/
+	async createSession(options) {
+		const cached = this.sessions.get(options.scanId);
+		if (cached !== void 0) {
+			this.ctx.logger.debug(`pentest-sandbox: reusing session for scan ${options.scanId}`);
+			return cached;
+		}
+		const config = this.config;
+		const subprocess = this.ctx.subprocess;
+		const cli = {
+			timeoutMs: config.defaultExecTimeoutMs,
+			graceMs: config.containerGraceMs,
+			collectMaxBytes: config.execCollectMaxBytes
+		};
+		let stagingDir;
+		let containerId;
+		try {
+			const mounts = buildBindMounts(options.sources ?? [], this.probe, config.workspaceRoot);
+			const extraMounts = await this.stageExtraFiles(options, config.workspaceRoot);
+			if (extraMounts.stagingDir !== void 0) stagingDir = extraMounts.stagingDir;
+			const allMounts = [...mounts, ...extraMounts.mounts].sort((a, b) => a.target.split("/").length - b.target.split("/").length || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+			const labels = {};
+			if (config.runLabelId !== void 0) labels["sharpkit-run-id"] = config.runLabelId;
+			if (config.runLabelType !== void 0) labels["sharpkit-run-type"] = config.runLabelType;
+			const spec = {
+				image: config.image,
+				command: KEEPALIVE_COMMAND,
+				env: buildContainerEnv({
+					caidoPort: CAIDO_PORT,
+					platform: process.platform,
+					uid: typeof process.getuid === "function" ? process.getuid() : void 0,
+					gid: typeof process.getgid === "function" ? process.getgid() : void 0
+				}),
+				bindMounts: allMounts,
+				caidoPort: CAIDO_PORT,
+				network: config.network,
+				caps: ["NET_ADMIN", "NET_RAW"],
+				extraHosts: { "host.docker.internal": "host-gateway" },
+				resourceLimits: {
+					memLimit: config.memLimit,
+					shmSize: config.shmSize,
+					cpus: config.cpus,
+					pidsLimit: config.pidsLimit
+				},
+				logMaxSize: config.logMaxSize,
+				logMaxFile: config.logMaxFile,
+				labels
+			};
+			await this.ensureImage(spec.image, cli);
+			const created = await runCollectArgv(subprocess, buildCreateArgv(spec), cli);
+			if (created.exitCode !== 0) throw new Error(`docker create failed (exit ${created.exitCode}): ${created.stderr.slice(0, 500)}`);
+			containerId = created.stdout.trim().split("\n").at(-1)?.trim() ?? "";
+			if (containerId === "") throw new Error("docker create produced no container id");
+			const started = await runCollectArgv(subprocess, buildStartArgv(containerId), cli);
+			if (started.exitCode !== 0) throw new Error(`docker start failed (exit ${started.exitCode}): ${started.stderr.slice(0, 500)}`);
+			const hostBaseUrl = await this.resolveCaidoHostUrl(containerId, cli);
+			const id = containerId;
+			const bootstrap = new CaidoBootstrap((signal) => bootstrapCaido((command, timeoutMs) => runCollectArgv(subprocess, [
+				"docker",
+				"exec",
+				"-i",
+				id,
+				"bash",
+				"-lc",
+				command
+			], {
+				...cli,
+				timeoutMs
+			}).then((result) => ({
+				ok: result.exitCode === 0,
+				exitCode: result.exitCode,
+				stdout: result.stdout,
+				stderr: result.stderr
+			})), fetch, {
+				containerBaseUrl: `http://127.0.0.1:${CAIDO_PORT}`,
+				hostBaseUrl
+			}, {
+				attempts: config.caidoLoginAttempts,
+				timeoutMs: config.caidoLoginTimeoutMs,
+				sleep: (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)),
+				signal
+			}));
+			const session = new DockerCliSandboxSession({
+				subprocess,
+				logger: this.ctx.logger,
+				containerId,
+				scanId: options.scanId,
+				containerCaidoBaseUrl: `http://127.0.0.1:${CAIDO_PORT}`,
+				hostCaidoBaseUrl: hostBaseUrl,
+				bootstrap,
+				stagingDir,
+				graceMs: config.containerGraceMs,
+				defaultExecTimeoutMs: config.defaultExecTimeoutMs,
+				collectMaxBytes: config.execCollectMaxBytes
+			});
+			this.sessions.set(options.scanId, session);
+			return session;
+		} catch (error) {
+			if (stagingDir !== void 0) await rm(stagingDir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+			if (containerId !== void 0) await runCollectArgv(subprocess, [
+				"docker",
+				"rm",
+				"-f",
+				containerId
+			], cli).catch(() => void 0);
+			throw error;
+		}
+	}
+	/** Stop and forget one session (idempotent; strix `cleanup`). */
+	async destroySession(scanId) {
+		const session = this.sessions.get(scanId);
+		if (session === void 0) {
+			this.ctx.logger.debug(`pentest-sandbox: no session to clean for scan ${scanId}`);
+			return;
+		}
+		this.sessions.delete(scanId);
+		await session.stop();
+	}
+	/** Validate + stage extra files (strix skip-and-warn semantics). */
+	async stageExtraFiles(options, workspaceRoot) {
+		const extraFiles = options.extraFiles ?? [];
+		if (extraFiles.length === 0) return { mounts: [] };
+		const sourceRoots = options.sources?.map((source) => source.workspaceSubdir) ?? [];
+		const placed = [];
+		const items = [];
+		for (const file of extraFiles) {
+			const rel = extraFileRelPath(file.containerPath, workspaceRoot);
+			if (rel === null) {
+				this.ctx.logger.warn(`pentest-sandbox: skipping invalid extra file path ${file.containerPath}`);
+				continue;
+			}
+			if (collidesWithRoots(rel, [...sourceRoots, ...placed])) {
+				this.ctx.logger.warn(`pentest-sandbox: skipping colliding extra file ${file.containerPath}`);
+				continue;
+			}
+			placed.push(rel);
+			items.push({
+				rel,
+				content: typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content
+			});
+		}
+		if (items.length === 0) return { mounts: [] };
+		const stagingDir = await mkdtemp(`${tmpdir()}/pentest-extra-files-${stagingDirName(options.scanId)}-`);
+		return {
+			mounts: await stageExtraFiles(stagingDir, items, workspaceRoot),
+			stagingDir
+		};
+	}
+	/** Pull the image when missing (strix image_exists → pull). */
+	async ensureImage(image, cli) {
+		if ((await runCollectArgv(this.ctx.subprocess, buildImageInspectArgv(image), {
+			...cli,
+			timeoutMs: 6e4
+		})).exitCode === 0) return;
+		this.ctx.logger.info(`pentest-sandbox: pulling image ${image}`);
+		const pulled = await runCollectArgv(this.ctx.subprocess, buildPullArgv(image), {
+			...cli,
+			timeoutMs: 18e5
+		});
+		if (pulled.exitCode !== 0) throw new Error(`docker pull failed (exit ${pulled.exitCode}): ${pulled.stderr.slice(0, 500)}`);
+	}
+	/** Resolve the host-side Caido base URL for a started container. */
+	async resolveCaidoHostUrl(containerId, cli) {
+		const config = this.config;
+		if (config.network !== void 0 && config.network !== "") {
+			const inspected = await runCollectArgv(this.ctx.subprocess, buildNetworkIpArgv(containerId, config.network), cli);
+			if (inspected.exitCode !== 0) throw new Error(`docker inspect (network ip) failed (exit ${inspected.exitCode}): ${inspected.stderr.slice(0, 500)}`);
+			const ip = inspected.stdout.trim();
+			if (ip === "") throw new Error(`container has no address on network ${config.network}`);
+			return `http://${ip.includes(":") ? `[${ip}]` : ip}:${CAIDO_PORT}`;
+		}
+		const port = await runCollectArgv(this.ctx.subprocess, buildPortArgv(containerId, CAIDO_PORT), cli);
+		if (port.exitCode !== 0) throw new Error(`docker port failed (exit ${port.exitCode}): ${port.stderr.slice(0, 500)}`);
+		const endpoint = parsePortOutput(port.stdout)[0];
+		if (endpoint === void 0) throw new Error(`caido port ${CAIDO_PORT} is not published for container ${containerId}`);
+		return `http://${endpoint.host}:${endpoint.port}`;
+	}
+};
+//#endregion
+export { PentestSandboxService, PentestSandboxService as default, SandboxProcessId, SandboxSessionId };
+
+//# sourceMappingURL=index.js.map