@agent-vm/gateway-interface 0.0.81 → 0.0.84

package/dist/index.js

@@ -25,6 +25,428 @@ function gatewayVmAllowedHosts(egressHosts) {
 	return Array.from(new Set([controllerVmHost, ...egressHostsForAudience(egressHosts, "gateway")]));
 }
 //#endregion
+//#region src/health/controller-request-policy.ts
+const gatewayInternalControllerRequestOperations = [
+	"controller-health",
+	"health-event-publish",
+	"openclaw-runtime-status",
+	"zone-git-push",
+	"lease-create",
+	"lease-get",
+	"lease-peek",
+	"lease-list",
+	"lease-renew",
+	"lease-release",
+	"lease-use-start",
+	"lease-heartbeat",
+	"lease-use-end"
+];
+const workerInternalControllerRequestOperations = ["worker-push-branches", "worker-pull-default"];
+const dedicatedControllerRequestHealthEventOperationSet = new Set(["lease-heartbeat", "lease-renew"]);
+function isGenericControllerRequestEventOperation(operation) {
+	return !dedicatedControllerRequestHealthEventOperationSet.has(operation);
+}
+const genericControllerRequestEventOperations = [...gatewayInternalControllerRequestOperations, ...workerInternalControllerRequestOperations].filter(isGenericControllerRequestEventOperation);
+const externalControllerRoutes = [
+	"GET /controller-status",
+	"GET /zones/:zoneId/status",
+	"GET /zones/:zoneId/health",
+	"GET /zones/:zoneId/zone-git/status",
+	"GET /zones/:zoneId/logs",
+	"POST /zones/:zoneId/credentials/refresh",
+	"POST /zones/:zoneId/destroy",
+	"POST /zones/:zoneId/upgrade",
+	"GET /zones/:zoneId/tasks/:taskId",
+	"POST /zones/:zoneId/worker-tasks",
+	"POST /zones/:zoneId/tasks/:taskId/close",
+	"POST /zones/:zoneId/enable-ssh",
+	"POST /zones/:zoneId/execute-command",
+	"POST /stop-controller"
+];
+var ControllerRequestPolicyTransportError = class extends Error {
+	code;
+	operation;
+	constructor(options) {
+		const causeMessage = options.cause instanceof Error ? options.cause.message : String(options.cause);
+		super(`${options.operation} ${options.code}: ${causeMessage}`, { cause: options.cause });
+		this.code = options.code;
+		this.operation = options.operation;
+	}
+};
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted === true) {
+			reject(signal.reason);
+			return;
+		}
+		const timeout = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timeout);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function shouldRetryResponse(response, policy) {
+	return policy.retryEnabled && policy.retryStatuses.includes(response.status);
+}
+async function drainControllerResponseBody(response) {
+	if (response.bodyUsed) return;
+	await response.text().catch(() => void 0);
+}
+async function fetchWithTimeout(options) {
+	const abortController = new AbortController();
+	let callerAborted = options.init?.signal?.aborted ?? false;
+	let timedOut = false;
+	const abortFromCaller = () => {
+		callerAborted = true;
+		abortController.abort(options.init?.signal?.reason);
+	};
+	const timeout = setTimeout(() => {
+		timedOut = true;
+		abortController.abort(/* @__PURE__ */ new Error(`${options.operation} timed out after ${String(options.timeoutMs)}ms`));
+	}, options.timeoutMs);
+	if (callerAborted) abortController.abort(options.init?.signal?.reason);
+	else options.init?.signal?.addEventListener("abort", abortFromCaller, { once: true });
+	try {
+		return await options.fetchImpl(options.input, {
+			...options.init,
+			signal: abortController.signal
+		});
+	} catch (error) {
+		if (callerAborted) throw error;
+		throw new ControllerRequestPolicyTransportError({
+			cause: error,
+			code: timedOut ? "controller-request-timeout" : "controller-request-failed",
+			operation: options.operation
+		});
+	} finally {
+		clearTimeout(timeout);
+		options.init?.signal?.removeEventListener("abort", abortFromCaller);
+	}
+}
+async function fetchControllerWithPolicy(options) {
+	const policy = options.policy ?? controllerRequestPolicies[options.operation];
+	const fetchImpl = options.fetchImpl ?? fetch;
+	let lastTransportError;
+	for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) try {
+		const response = await fetchWithTimeout({
+			fetchImpl,
+			init: options.init,
+			input: options.input,
+			operation: options.operation,
+			timeoutMs: policy.timeoutMs
+		});
+		if (attempt < policy.maxAttempts && shouldRetryResponse(response, policy)) {
+			await drainControllerResponseBody(response);
+			if (policy.retryBaseDelayMs > 0) await sleep(policy.retryBaseDelayMs, options.init?.signal ?? void 0);
+			continue;
+		}
+		return response;
+	} catch (error) {
+		if (!(error instanceof ControllerRequestPolicyTransportError)) throw error;
+		lastTransportError = error;
+		if (!(policy.retryEnabled && attempt < policy.maxAttempts)) throw error;
+		if (policy.retryBaseDelayMs > 0) await sleep(policy.retryBaseDelayMs, options.init?.signal ?? void 0);
+	}
+	throw lastTransportError ?? /* @__PURE__ */ new Error(`${options.operation} failed without a response`);
+}
+const controllerRequestPolicies = {
+	"controller-health": {
+		idempotency: "read",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 3e3
+	},
+	"health-event-publish": {
+		idempotency: "safe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 3e3
+	},
+	"openclaw-runtime-status": {
+		idempotency: "safe-mutation",
+		maxAttempts: 30,
+		retryBaseDelayMs: 1e3,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 3e3
+	},
+	"zone-git-push": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	},
+	"lease-create": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 18e4
+	},
+	"lease-get": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-peek": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-list": {
+		idempotency: "read",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-renew": {
+		idempotency: "safe-mutation",
+		maxAttempts: 3,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 1e4
+	},
+	"lease-release": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"lease-use-start": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 1e4
+	},
+	"lease-heartbeat": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [
+			429,
+			503,
+			504
+		],
+		timeoutMs: 5e3
+	},
+	"lease-use-end": {
+		idempotency: "safe-mutation",
+		maxAttempts: 2,
+		retryBaseDelayMs: 250,
+		retryEnabled: true,
+		retryStatuses: [503, 504],
+		timeoutMs: 5e3
+	},
+	"worker-push-branches": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	},
+	"worker-pull-default": {
+		idempotency: "unsafe-mutation",
+		maxAttempts: 1,
+		retryBaseDelayMs: 0,
+		retryEnabled: false,
+		retryStatuses: [],
+		timeoutMs: 12e4
+	}
+};
+//#endregion
+//#region src/health/agent-vm-health.ts
+const agentVmHealthEventKinds = [
+	"gateway-service-health",
+	"gateway-control-link",
+	"controller-request",
+	"lease-renew",
+	"lease-heartbeat",
+	"tool-vm-ssh",
+	"gateway-plugin-health"
+];
+const agentVmHealthResultKinds = [
+	"ok",
+	"failed",
+	"timeout",
+	"stale"
+];
+const gatewayControlLinkHealthPins = {
+	controllerHost: "controller.vm.host",
+	controllerPort: 18800,
+	operation: "controller-health",
+	path: "/health"
+};
+const zoneHealthStateKinds = [
+	"unknown",
+	"ok",
+	"stale",
+	"failed"
+];
+const zoneHealthIssueKinds = [
+	"gateway-service-unhealthy",
+	"gateway-control-link-unhealthy",
+	"controller-request-failing",
+	"lease-heartbeat-failing",
+	"lease-renew-failing",
+	"tool-vm-ssh-failing",
+	"gateway-plugin-unhealthy",
+	"health-event-stale"
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(values, value) {
+	return typeof value === "string" && values.includes(value);
+}
+function isNonNegativeFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function hasBaseEventFields(record) {
+	return isNonNegativeFiniteNumber(record.observedAtMs) && isOneOf(agentVmHealthResultKinds, record.result) && typeof record.zoneId === "string" && record.zoneId.length > 0;
+}
+function optionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function optionalStatusCode(value) {
+	return value === void 0 || Number.isInteger(value);
+}
+function isAgentVmHealthEvent(value) {
+	if (!isRecord(value) || !hasBaseEventFields(value)) return false;
+	switch (value.kind) {
+		case "gateway-service-health": return typeof value.path === "string" && value.path.length > 0 && Number.isInteger(value.port) && optionalStatusCode(value.statusCode);
+		case "gateway-control-link": return value.controllerHost === gatewayControlLinkHealthPins.controllerHost && value.controllerPort === gatewayControlLinkHealthPins.controllerPort && isNonNegativeFiniteNumber(value.elapsedMs) && value.operation === gatewayControlLinkHealthPins.operation && value.path === gatewayControlLinkHealthPins.path;
+		case "controller-request": return Number.isInteger(value.attempt) && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && Number.isInteger(value.maxAttempts) && isOneOf(genericControllerRequestEventOperations, value.operation) && optionalStatusCode(value.statusCode);
+		case "lease-renew": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string";
+		case "lease-heartbeat": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string" && typeof value.useId === "string";
+		case "tool-vm-ssh": return typeof value.agentId === "string" && isNonNegativeFiniteNumber(value.elapsedMs) && optionalString(value.errorCode) && typeof value.leaseId === "string" && isOneOf([
+			"command",
+			"file-bridge",
+			"finalize",
+			"probe"
+		], value.operation);
+		case "gateway-plugin-health": return isOneOf(gatewayTypeValues, value.gatewayService) && isOneOf([
+			"starting",
+			"ready",
+			"stopping",
+			"failed"
+		], value.state);
+		default: return false;
+	}
+}
+function healthEventBucketKey(event) {
+	switch (event.kind) {
+		case "gateway-control-link": return `${event.zoneId}:${event.kind}`;
+		case "gateway-service-health": return `${event.zoneId}:${event.kind}:${event.port}:${event.path}`;
+		case "controller-request": return `${event.zoneId}:${event.kind}:${event.operation}`;
+		case "lease-heartbeat": return `${event.zoneId}:${event.kind}:${event.leaseId}:${event.useId}`;
+		case "lease-renew": return `${event.zoneId}:${event.kind}:${event.leaseId}`;
+		case "tool-vm-ssh": return `${event.zoneId}:${event.kind}:${event.leaseId}:${event.operation}`;
+		case "gateway-plugin-health": return `${event.zoneId}:${event.kind}:${event.gatewayService}`;
+	}
+	return assertNeverHealthEvent(event);
+}
+function failedIssueKindForEvent(event) {
+	switch (event.kind) {
+		case "gateway-service-health": return "gateway-service-unhealthy";
+		case "gateway-control-link": return "gateway-control-link-unhealthy";
+		case "controller-request": return "controller-request-failing";
+		case "lease-heartbeat": return "lease-heartbeat-failing";
+		case "lease-renew": return "lease-renew-failing";
+		case "tool-vm-ssh": return "tool-vm-ssh-failing";
+		case "gateway-plugin-health": return "gateway-plugin-unhealthy";
+	}
+	return assertNeverHealthEvent(event);
+}
+function assertNeverHealthEvent(event) {
+	throw new Error(`Unhandled health event kind: ${JSON.stringify(event)}`);
+}
+function issueForEvent(event, options) {
+	if (options.nowMs - event.observedAtMs > options.staleAfterMs) return {
+		kind: "health-event-stale",
+		latestEvent: event,
+		message: `${event.kind} health event is stale`,
+		sinceMs: event.observedAtMs
+	};
+	if (event.result === "failed" || event.result === "timeout" || event.result === "stale") return {
+		kind: failedIssueKindForEvent(event),
+		latestEvent: event,
+		message: `${event.kind} health event reported ${event.result}`,
+		sinceMs: event.observedAtMs
+	};
+}
+function deriveZoneHealthSnapshot(events, options) {
+	const latestByKey = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.zoneId !== options.zoneId) continue;
+		const key = healthEventBucketKey(event);
+		const previous = latestByKey.get(key);
+		if (!previous || previous.observedAtMs <= event.observedAtMs) latestByKey.set(key, event);
+	}
+	const latestEvents = [...latestByKey.values()].toSorted((first, second) => second.observedAtMs - first.observedAtMs);
+	if (latestEvents.length === 0) return {
+		kind: "unknown",
+		reason: "no-events",
+		zoneId: options.zoneId
+	};
+	const issues = latestEvents.map((event) => issueForEvent(event, options)).filter((issue) => issue !== void 0);
+	if (issues.length === 0) return {
+		kind: "ok",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+	if (issues.some((issue) => issue.kind === "health-event-stale")) return {
+		issues,
+		kind: "stale",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+	return {
+		issues,
+		kind: "failed",
+		latestEvents,
+		zoneId: options.zoneId
+	};
+}
+//#endregion
 //#region src/force-ipv4-egress.ts
 /**
 * Canonical NODE_OPTIONS value for forcing IPv4-preference egress
@@ -62,6 +484,7 @@ function gatewayVmAllowedHosts(egressHosts) {
 * revert recommendation by the Node core team).
 */
 const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-network-family-autoselection";
+const FORCE_IPV4_EGRESS_NODE_OPTION_FLAGS = FORCE_IPV4_EGRESS_NODE_OPTIONS.split(/\s+/u);
 /**
 * Compose the forced IPv4-preference flags with a user-provided
 * NODE_OPTIONS value (if any).
@@ -72,8 +495,9 @@ const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-networ
 * a zone secret happens to provide its own NODE_OPTIONS.
 *
 * Forced flags come FIRST so they are unambiguously applied.
-* User-provided flags are appended verbatim. Node treats NODE_OPTIONS
-* as a whitespace-separated list and all flags apply.
+* User-provided flags are appended verbatim except for duplicate
+* forced IPv4-preference flags. Node treats NODE_OPTIONS as a
+* whitespace-separated list and all flags apply.
 *
 * Returns just the forced flags if the user value is undefined,
 * empty, or whitespace-only.
@@ -93,7 +517,9 @@ const FORCE_IPV4_EGRESS_NODE_OPTIONS = "--dns-result-order=ipv4first --no-networ
 function composeNodeOptions(userValue) {
 	const trimmed = userValue?.trim() ?? "";
 	if (trimmed === "") return FORCE_IPV4_EGRESS_NODE_OPTIONS;
-	return `${FORCE_IPV4_EGRESS_NODE_OPTIONS} ${trimmed}`;
+	const userFlags = trimmed.split(/\s+/u).filter((flag) => !FORCE_IPV4_EGRESS_NODE_OPTION_FLAGS.includes(flag));
+	if (userFlags.length === 0) return FORCE_IPV4_EGRESS_NODE_OPTIONS;
+	return `${FORCE_IPV4_EGRESS_NODE_OPTIONS} ${userFlags.join(" ")}`;
 }
 //#endregion
 //#region src/split-resolved-gateway-secrets.ts
@@ -153,6 +579,12 @@ function mergeRuntimeGatewaySecrets(baseSecrets, options = {}) {
 //#endregion
 //#region src/tool-vm-active-use.ts
 const defaultMaxHeartbeatDurationMs = 720 * 60 * 1e3;
+function jitterDelayMs(params) {
+	if (params.jitterRatio <= 0) return params.delayMs;
+	const spreadMs = params.delayMs * params.jitterRatio;
+	const jitteredMs = params.delayMs - spreadMs + params.random() * spreadMs * 2;
+	return Math.max(1, Math.round(jitteredMs));
+}
 function createToolVmActiveUseId() {
 	return v7();
 }
@@ -170,8 +602,12 @@ async function createToolVmActiveUseHandle(options) {
 	const now = options.nowImpl ?? Date.now;
 	const startedAt = now();
 	const maxHeartbeatDurationMs = options.maxHeartbeatDurationMs ?? defaultMaxHeartbeatDurationMs;
+	const heartbeatJitterRatio = options.heartbeatJitterRatio ?? .1;
+	const random = options.randomImpl ?? Math.random;
+	const operationAbortController = new AbortController();
 	let ended = false;
 	let heartbeatTimer;
+	let latestReport;
 	const clearHeartbeatTimer = () => {
 		if (heartbeatTimer) {
 			clearTimeoutImpl(heartbeatTimer);
@@ -183,13 +619,27 @@ async function createToolVmActiveUseHandle(options) {
 		clearHeartbeatTimer();
 		heartbeatTimer = setTimeoutImpl(() => {
 			if (now() - startedAt >= maxHeartbeatDurationMs) return;
-			options.heartbeatActiveUse(startedUse.useId).then((heartbeat) => {
+			const heartbeatRequest = latestReport === void 0 ? {} : { report: latestReport };
+			options.heartbeatActiveUse(startedUse.useId, heartbeatRequest).then((heartbeat) => {
 				if (!ended) scheduleHeartbeat(heartbeat.heartbeatAfterMs);
 			}).catch((error) => {
 				options.logHeartbeatFailure?.(error);
+				if (options.isHeartbeatErrorRefreshable?.(error) === true && options.onRefreshableHeartbeatFailure) {
+					operationAbortController.abort(error);
+					ended = true;
+					clearHeartbeatTimer();
+					options.onRefreshableHeartbeatFailure(error).catch((staleError) => {
+						options.logHeartbeatFailure?.(staleError);
+					});
+					return;
+				}
 				if (!ended) scheduleHeartbeat(startedUse.heartbeatAfterMs);
 			});
-		}, delayMs);
+		}, jitterDelayMs({
+			delayMs,
+			jitterRatio: heartbeatJitterRatio,
+			random
+		}));
 	};
 	scheduleHeartbeat(startedUse.heartbeatAfterMs);
 	const end = async (outcome = "completed") => {
@@ -197,7 +647,10 @@ async function createToolVmActiveUseHandle(options) {
 		ended = true;
 		clearHeartbeatTimer();
 		try {
-			await options.endActiveUse(startedUse.useId, { outcome });
+			await options.endActiveUse(startedUse.useId, {
+				outcome,
+				...latestReport === void 0 ? {} : { report: latestReport }
+			});
 		} catch (error) {
 			if (options.isEndErrorTolerable?.(error) === true) {
 				options.logEndFailure?.(error);
@@ -207,11 +660,190 @@ async function createToolVmActiveUseHandle(options) {
 		}
 	};
 	return {
+		signal: operationAbortController.signal,
 		useId: startedUse.useId,
 		dispose: end,
-		end
+		end,
+		report: (report) => {
+			if (ended) return;
+			latestReport = report;
+		}
+	};
+}
+//#endregion
+//#region src/runtime-paths/runtime-path-mapping.ts
+const TOOL_VM_WORKSPACE_GUEST_ROOT = "/workspace";
+const TOOL_VM_SCRATCH_GUEST_ROOT = "/work";
+const OPENCLAW_STATE_VM_ROOT = "/home/openclaw/.openclaw/state";
+const OPENCLAW_STATE_SANDBOXES_VM_ROOT = `${OPENCLAW_STATE_VM_ROOT}/sandboxes`;
+const guidanceNamespaceOrder = [
+	"tool-vm-guest",
+	"openclaw-gateway",
+	"controller-host"
+];
+function pathContainsParentTraversal(inputPath) {
+	return inputPath.split(/\/+/u).includes("..");
+}
+function normalizeAbsolutePath(inputPath) {
+	return `/${inputPath.split("/").filter((segment) => segment !== "" && segment !== ".").join("/")}`;
+}
+function normalizeRoot(rootPath) {
+	const normalizedRoot = normalizeAbsolutePath(rootPath);
+	return normalizedRoot === "/" ? normalizedRoot : normalizedRoot.replace(/\/+$/u, "");
+}
+function pathMatchesRoot(candidatePath, rootPath) {
+	return candidatePath === rootPath || candidatePath.startsWith(`${rootPath}/`);
+}
+function relativePathForRoot(candidatePath, rootPath) {
+	return candidatePath === rootPath ? "" : candidatePath.slice(rootPath.length + 1);
+}
+function joinRootAndRelative(rootPath, relativePath) {
+	return relativePath === "" ? rootPath : `${rootPath}/${relativePath}`;
+}
+function runtimeRootIsInvalid(rootPath) {
+	return rootPath.trim() === "" || !rootPath.startsWith("/") || pathContainsParentTraversal(rootPath);
+}
+function namespaceShouldShowInGuidance(root, namespace) {
+	if (root.showInGuidance?.[namespace] !== void 0) return root.showInGuidance[namespace];
+	return namespace !== "controller-host";
+}
+function allowedPathFormsForMapping(mapping, purpose) {
+	return mapping.roots.flatMap((root) => {
+		if (!root.capabilities[purpose]) return [];
+		const suffix = root.rootPathAllowed ? "[/subpath]" : "/<child>";
+		return guidanceNamespaceOrder.flatMap((namespace) => {
+			const rootPath = root.locations[namespace];
+			if (rootPath === void 0 || !namespaceShouldShowInGuidance(root, namespace)) return [];
+			return [`${normalizeRoot(rootPath)}${suffix}`];
+		});
+	});
+}
+function retryGuidanceForMapping(mapping, purpose) {
+	return `Use one of the allowed path forms for ${mapping.id} ${purpose}: ${allowedPathFormsForMapping(mapping, purpose).join(", ")}.`;
+}
+function errorResult(params) {
+	return {
+		error: {
+			allowedPathForms: allowedPathFormsForMapping(params.mapping, params.purpose),
+			code: params.code,
+			inputPath: params.inputPath,
+			mappingId: params.mapping.id,
+			message: params.message,
+			purpose: params.purpose,
+			retryGuidance: retryGuidanceForMapping(params.mapping, params.purpose)
+		},
+		ok: false
 	};
 }
+function findBestRootMatch(params) {
+	return params.mapping.roots.flatMap((root) => guidanceNamespaceOrder.flatMap((inputNamespace) => {
+		const rootPath = root.locations[inputNamespace];
+		if (rootPath === void 0) return [];
+		if (params.sourceNamespace !== void 0 && inputNamespace !== params.sourceNamespace) return [];
+		const normalizedRoot = normalizeRoot(rootPath);
+		return pathMatchesRoot(params.inputPath, normalizedRoot) ? [{
+			inputNamespace,
+			matchedRoot: normalizedRoot,
+			root
+		}] : [];
+	})).toSorted((left, right) => right.matchedRoot.length - left.matchedRoot.length)[0];
+}
+function findInvalidRoot(mapping) {
+	for (const root of mapping.roots) for (const namespace of guidanceNamespaceOrder) {
+		const rootPath = root.locations[namespace];
+		if (rootPath !== void 0 && runtimeRootIsInvalid(rootPath)) return {
+			rootId: root.id,
+			rootPath
+		};
+	}
+}
+function translateRuntimePath(input) {
+	if (!input.inputPath.startsWith("/")) return errorResult({
+		code: "path-not-absolute",
+		inputPath: input.inputPath,
+		mapping: input.mapping,
+		message: `Path '${input.inputPath}' must be absolute.`,
+		purpose: input.purpose
+	});
+	if (pathContainsParentTraversal(input.inputPath)) return errorResult({
+		code: "path-parent-traversal",
+		inputPath: input.inputPath,
+		mapping: input.mapping,
+		message: `Path '${input.inputPath}' must not contain parent traversal.`,
+		purpose: input.purpose
+	});
+	const invalidRoot = findInvalidRoot(input.mapping);
+	if (invalidRoot !== void 0) return errorResult({
+		code: "invalid-runtime-root",
+		inputPath: input.inputPath,
+		mapping: input.mapping,
+		message: `Runtime path root '${invalidRoot.rootId}' has invalid path '${invalidRoot.rootPath}'.`,
+		purpose: input.purpose
+	});
+	const normalizedInputPath = normalizeAbsolutePath(input.inputPath);
+	const match = findBestRootMatch({
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		...input.sourceNamespace === void 0 ? {} : { sourceNamespace: input.sourceNamespace }
+	});
+	if (match === void 0) return errorResult({
+		code: "unknown-runtime-path",
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		message: `Path '${normalizedInputPath}' is not part of runtime path mapping '${input.mapping.id}'.`,
+		purpose: input.purpose
+	});
+	const relativePath = relativePathForRoot(normalizedInputPath, match.matchedRoot);
+	if (relativePath === "" && !match.root.rootPathAllowed) return errorResult({
+		code: "root-path-not-allowed",
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		message: `Path '${normalizedInputPath}' matched ${match.root.guidanceLabel}, but the root itself is not allowed for ${input.purpose}.`,
+		purpose: input.purpose
+	});
+	if (!match.root.capabilities[input.purpose]) return errorResult({
+		code: "purpose-not-allowed",
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		message: `Path '${normalizedInputPath}' matched ${match.root.guidanceLabel} but cannot be used for ${input.purpose}.`,
+		purpose: input.purpose
+	});
+	const targetRoot = match.root.locations[input.targetNamespace];
+	if (targetRoot === void 0) return errorResult({
+		code: "target-namespace-not-available",
+		inputPath: normalizedInputPath,
+		mapping: input.mapping,
+		message: `Path '${normalizedInputPath}' matched ${match.root.guidanceLabel}, but '${input.targetNamespace}' is not available for that root.`,
+		purpose: input.purpose
+	});
+	const normalizedTargetRoot = normalizeRoot(targetRoot);
+	return {
+		ok: true,
+		value: {
+			backing: match.root.backing,
+			capabilities: match.root.capabilities,
+			inputNamespace: match.inputNamespace,
+			inputPath: normalizedInputPath,
+			mappingId: input.mapping.id,
+			outputNamespace: input.targetNamespace,
+			outputPath: joinRootAndRelative(normalizedTargetRoot, relativePath),
+			relativePath,
+			rootId: match.root.id
+		}
+	};
+}
+//#endregion
+//#region src/tool-vm-lease-id.ts
+function createToolVmLeaseId() {
+	return parseToolVmLeaseId(v7());
+}
+function isToolVmLeaseId(value) {
+	return typeof value === "string" && validate(value) && version(value) === 7;
+}
+function parseToolVmLeaseId(value) {
+	if (isToolVmLeaseId(value)) return value;
+	throw new TypeError("Tool VM lease id must be an opaque UUIDv7 string.");
+}
 //#endregion
 //#region src/vm-capability-lease.ts
 const VM_SSH_PUBLIC_ENDPOINT_KEYS = new Set([
@@ -244,15 +876,16 @@ function isVmSshPublicEndpoint(value) {
 function objectValue(value) {
 	return typeof value === "object" && value !== null ? value : void 0;
 }
+const deprecatedScopeKeyPropertyName = ["scope", "Key"].join("");
 function isToolVmSshLease(value) {
 	const record = objectValue(value);
-	return isVmCapabilityLease(record, "ssh-sandbox") && isVmSshEndpoint(Reflect.get(record, "ssh")) && typeof Reflect.get(record, "agentId") === "string" && typeof Reflect.get(record, "scopeKey") === "string" && typeof Reflect.get(record, "tcpSlot") === "number" && typeof Reflect.get(record, "workdir") === "string";
+	return isVmCapabilityLease(record, "ssh-sandbox") && isToolVmLeaseId(Reflect.get(record, "leaseId")) && isVmSshEndpoint(Reflect.get(record, "ssh")) && typeof Reflect.get(record, "agentId") === "string" && typeof Reflect.get(record, "idleTtlMs") === "number" && typeof Reflect.get(record, "tcpSlot") === "number" && typeof Reflect.get(record, "workdir") === "string" && !Reflect.has(record, deprecatedScopeKeyPropertyName);
 }
 function isToolVmLeasePeek(value) {
 	const record = objectValue(value);
-	return isVmCapabilityLease(record, "ssh-sandbox") && typeof Reflect.get(record, "agentId") === "string" && typeof Reflect.get(record, "createdAt") === "number" && typeof Reflect.get(record, "lastUsedAt") === "number" && typeof Reflect.get(record, "profileId") === "string" && typeof Reflect.get(record, "scopeKey") === "string" && isVmSshPublicEndpoint(Reflect.get(record, "ssh")) && typeof Reflect.get(record, "tcpSlot") === "number" && typeof Reflect.get(record, "workdir") === "string" && typeof Reflect.get(record, "zoneId") === "string";
+	return isVmCapabilityLease(record, "ssh-sandbox") && isToolVmLeaseId(Reflect.get(record, "leaseId")) && typeof Reflect.get(record, "agentId") === "string" && typeof Reflect.get(record, "createdAt") === "number" && typeof Reflect.get(record, "idleTtlMs") === "number" && typeof Reflect.get(record, "lastUsedAt") === "number" && typeof Reflect.get(record, "profileId") === "string" && isVmSshPublicEndpoint(Reflect.get(record, "ssh")) && typeof Reflect.get(record, "tcpSlot") === "number" && typeof Reflect.get(record, "workdir") === "string" && typeof Reflect.get(record, "zoneId") === "string" && !Reflect.has(record, deprecatedScopeKeyPropertyName);
 }
 //#endregion
-export { FORCE_IPV4_EGRESS_NODE_OPTIONS, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerVmHost, createToolVmActiveUseHandle, createToolVmActiveUseId, egressHostsForAudience, gatewayTypeValues, gatewayVmAllowedHosts, isToolVmActiveUseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, vmAudienceValues };
+export { ControllerRequestPolicyTransportError, FORCE_IPV4_EGRESS_NODE_OPTIONS, OPENCLAW_STATE_SANDBOXES_VM_ROOT, OPENCLAW_STATE_VM_ROOT, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORKSPACE_GUEST_ROOT, agentVmHealthEventKinds, agentVmHealthResultKinds, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerRequestPolicies, controllerVmHost, createToolVmActiveUseHandle, createToolVmActiveUseId, createToolVmLeaseId, deriveZoneHealthSnapshot, drainControllerResponseBody, egressHostsForAudience, externalControllerRoutes, fetchControllerWithPolicy, gatewayControlLinkHealthPins, gatewayInternalControllerRequestOperations, gatewayTypeValues, gatewayVmAllowedHosts, genericControllerRequestEventOperations, healthEventBucketKey, isAgentVmHealthEvent, isToolVmActiveUseId, isToolVmLeaseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, parseToolVmLeaseId, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, translateRuntimePath, vmAudienceValues, workerInternalControllerRequestOperations, zoneHealthIssueKinds, zoneHealthStateKinds };
 
 //# sourceMappingURL=index.js.map