@agent-vm/gateway-lifecycle 0.0.115

package/dist/index.js

@@ -0,0 +1,1323 @@
+import { v7, validate, version } from "uuid";
+//#region src/gateway-runtime-contract.ts
+const gatewayTypeValues = [
+	"openclaw",
+	"hermes",
+	"worker"
+];
+function buildGatewaySessionLabel(projectNamespace, zoneId) {
+	return `${projectNamespace}:${zoneId}:gateway`;
+}
+function buildToolSessionLabel(projectNamespace, zoneId, tcpSlot) {
+	return `${projectNamespace}:${zoneId}:tool:${tcpSlot}`;
+}
+//#endregion
+//#region src/gateway-lifecycle.ts
+const gatewayToolPortalTelemetryServiceName = "agent-vm-tool-portal";
+const gatewayFrameworkTelemetryServiceNames = Object.freeze({
+	hermes: "agent-vm-hermes",
+	openclaw: "agent-vm-openclaw"
+});
+const gatewayTelemetrySourcePolicy = Object.freeze({
+	admitBaggage: false,
+	captureContent: false
+});
+const gatewayTelemetryAdmissionLimits = Object.freeze({
+	maxExportBatchRecords: 64,
+	maxQueuedRecordsPerSignal: 256,
+	maxRecordBytes: 65536
+});
+function createGatewayTelemetryProducerSafetyContract() {
+	if (gatewayTelemetryAdmissionLimits.maxExportBatchRecords > gatewayTelemetryAdmissionLimits.maxQueuedRecordsPerSignal) throw new Error("Gateway telemetry maxExportBatchRecords must not exceed maxQueuedRecordsPerSignal.");
+	return {
+		admissionLimits: { ...gatewayTelemetryAdmissionLimits },
+		sourcePolicy: { ...gatewayTelemetrySourcePolicy }
+	};
+}
+//#endregion
+//#region src/audience.ts
+const vmAudienceValues = [
+	"gateway",
+	"tool-vm",
+	"both"
+];
+const controllerVmHost = "controller.vm.host";
+function targetsAudience(configAudience, runtimeAudience) {
+	return configAudience === runtimeAudience || configAudience === "both";
+}
+function egressHostsForAudience(egressHosts, runtimeAudience) {
+	return egressHosts.filter((egressHost) => targetsAudience(egressHost.audience, runtimeAudience)).map((egressHost) => egressHost.host);
+}
+function gatewayVmAllowedHosts(egressHosts) {
+	return Array.from(new Set(egressHostsForAudience(egressHosts, "gateway").filter((host) => host !== controllerVmHost)));
+}
+function workerVmAllowedHosts(egressHosts) {
+	return Array.from(new Set(egressHostsForAudience(egressHosts, "gateway").filter((host) => host !== controllerVmHost)));
+}
+//#endregion
+//#region src/websocket-upgrade-policy.ts
+function escapeRegExpLiteral(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function hostMatchesPattern(host, pattern) {
+	const normalizedPattern = pattern.trim().toLowerCase();
+	if (normalizedPattern === "") return false;
+	if (normalizedPattern === "*") return true;
+	return new RegExp(`^${normalizedPattern.split("*").map(escapeRegExpLiteral).join(".*")}$`, "iu").test(host.toLowerCase());
+}
+function isWebSocketUpgradeRequest(request) {
+	const upgrade = request.headers.get("upgrade")?.toLowerCase() ?? "";
+	const connection = request.headers.get("connection")?.toLowerCase() ?? "";
+	return upgrade === "websocket" || connection.split(",").map((token) => token.trim()).includes("upgrade") || request.headers.has("sec-websocket-key") || request.headers.has("sec-websocket-version");
+}
+function requestSchemeForRule(url) {
+	if (url.protocol === "http:") return "ws";
+	if (url.protocol === "https:") return "wss";
+	return null;
+}
+function requestPortForScheme(url, scheme) {
+	if (url.port.length > 0) return Number.parseInt(url.port, 10);
+	return scheme === "wss" ? 443 : 80;
+}
+function defaultPortForScheme(scheme) {
+	return scheme === "wss" ? 443 : 80;
+}
+function websocketRuleMatchesRequest(rule, request) {
+	const url = new URL(request.url);
+	const requestScheme = requestSchemeForRule(url);
+	if (requestScheme !== rule.scheme) return false;
+	if (!hostMatchesPattern(url.hostname, rule.host)) return false;
+	if (requestPortForScheme(url, requestScheme) !== (rule.port ?? defaultPortForScheme(rule.scheme))) return false;
+	if (rule.path !== void 0 && url.pathname !== rule.path) return false;
+	return true;
+}
+function websocketUpgradesForAudience(rules, runtimeAudience) {
+	return (rules ?? []).filter((rule) => targetsAudience(rule.audience, runtimeAudience));
+}
+function createWebSocketUpgradeRequestGuard(options) {
+	const runtimeRules = websocketUpgradesForAudience(options.rules, options.runtimeAudience);
+	return async (request) => {
+		if (!isWebSocketUpgradeRequest(request)) return;
+		if (runtimeRules.some((rule) => websocketRuleMatchesRequest(rule, request))) return;
+		return new Response("WebSocket upgrade blocked by agent-vm policy", {
+			status: 403,
+			statusText: "Forbidden"
+		});
+	};
+}
+//#endregion
+//#region src/gateway-control-private-environment.ts
+const GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY_ENV = "AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY";
+const GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS_ENV = "AGENT_VM_GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS";
+const GATEWAY_CONTROL_PRIVATE_ENVIRONMENT_NAMES = [GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS_ENV, GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY_ENV];
+//#endregion
+//#region src/health/controller-request-policy.ts
+const gatewayInternalControllerRequestOperations = [
+	"workspace-git-push",
+	"lease-create",
+	"lease-get",
+	"lease-peek",
+	"lease-renew",
+	"lease-release",
+	"lease-use-start",
+	"lease-heartbeat",
+	"lease-use-end"
+];
+const dedicatedControllerRequestHealthEventOperationSet = new Set(["lease-heartbeat", "lease-renew"]);
+function isGenericControllerRequestEventOperation(operation) {
+	return !dedicatedControllerRequestHealthEventOperationSet.has(operation);
+}
+const genericControllerRequestEventOperations = [...gatewayInternalControllerRequestOperations].filter(isGenericControllerRequestEventOperation);
+const externalControllerRoutes = [
+	"GET /controller-status",
+	"GET /zones/:zoneId/status",
+	"GET /zones/:zoneId/health",
+	"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;
+	}
+};
+async function drainControllerResponseBody(response) {
+	if (response.bodyUsed) return;
+	await response.text().catch(() => void 0);
+}
+const controllerRequestPolicies = {
+	"workspace-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-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
+	}
+};
+//#endregion
+//#region src/health/agent-vm-health.ts
+const agentVmHealthEventKinds = [
+	"gateway-service-health",
+	"gateway-control-session",
+	"controller-request",
+	"lease-renew",
+	"lease-heartbeat",
+	"caller-context-rejection",
+	"tool-vm-ssh",
+	"gateway-plugin-health",
+	"agent-channel-provider-health",
+	"gateway-recovery",
+	"gateway-recovery-suspended"
+];
+const agentVmHealthResultKinds = [
+	"ok",
+	"failed",
+	"timeout",
+	"stale"
+];
+const toolVmLeaseLifecycleEventRoles = ["plugin_observation", "controller_final"];
+const toolVmLeaseLifecycleTransitions = [
+	"current_to_stale",
+	"current_to_retired",
+	"deprecated_to_reacquired",
+	"deprecated_to_retired",
+	"stale_to_reacquired",
+	"stale_to_retired",
+	"retired_rejected"
+];
+const toolVmLeaseReacquiredLifecycleTransitions = ["deprecated_to_reacquired", "stale_to_reacquired"];
+const toolVmLeaseCallerContextStates = [
+	"ok",
+	"absent",
+	"stale",
+	"session_mismatch",
+	"not_applicable"
+];
+const toolVmLeaseRejectionReasons = [
+	"caller_context_absent",
+	"caller_context_session_mismatch",
+	"caller_context_stale",
+	"lease_absent",
+	"lease_authority_absent",
+	"lease_force_released",
+	"lease_generation_stale",
+	"lease_reacquire_required",
+	"lease_releasing",
+	"lease_retired",
+	"lease_use_tombstoned",
+	"ownership_denied",
+	"runtime_not_ready"
+];
+const agentChannelProviderHealthKinds = [
+	"healthy",
+	"transitioning",
+	"unhealthy-recoverable",
+	"unhealthy-unrecoverable"
+];
+const agentChannelProviderHealthDetailKeys = [
+	"closeCode",
+	"providerType",
+	"reconnectAttempt",
+	"reconnecting",
+	"sleepResumeSuspected",
+	"statusCode"
+];
+const gatewayRecoveryHealthReasons = [
+	"agent-channel-provider-unhealthy",
+	"gateway-control-session-unhealthy",
+	"gateway-service-unhealthy"
+];
+const gatewayControlSessionHealthOperations = [
+	"control-session-hello",
+	"control-session-heartbeat",
+	"control-session-disconnect",
+	"control-session-reconnect"
+];
+const zoneHealthStateKinds = [
+	"unknown",
+	"ok",
+	"stale",
+	"failed"
+];
+const zoneHealthIssueKinds = [
+	"gateway-service-unhealthy",
+	"gateway-control-session-unhealthy",
+	"controller-request-failing",
+	"lease-heartbeat-failing",
+	"lease-renew-failing",
+	"tool-vm-ssh-failing",
+	"gateway-plugin-unhealthy",
+	"agent-channel-provider-unhealthy",
+	"gateway-recovery-failed",
+	"gateway-recovery-suspended",
+	"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 optionalNonEmptyString(value) {
+	return value === void 0 || typeof value === "string" && value.length > 0;
+}
+function optionalOneOf(values, value) {
+	return value === void 0 || isOneOf(values, value);
+}
+function isToolVmLeaseReacquiredTransition(value) {
+	return isOneOf(toolVmLeaseReacquiredLifecycleTransitions, value);
+}
+function optionalStatusCode(value) {
+	return value === void 0 || Number.isInteger(value);
+}
+function optionalNonNegativeInteger(value) {
+	return value === void 0 || Number.isInteger(value) && Number(value) >= 0;
+}
+function isNonNegativeInteger(value) {
+	return Number.isInteger(value) && Number(value) >= 0;
+}
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && Number(value) > 0;
+}
+function isRedactedHealthDetails(value) {
+	if (value === void 0) return true;
+	if (!isRecord(value)) return false;
+	for (const [key, detailValue] of Object.entries(value)) {
+		if (!isOneOf(agentChannelProviderHealthDetailKeys, key)) return false;
+		if (!isChannelProviderHealthDetailValue(key, detailValue)) return false;
+	}
+	return true;
+}
+function isChannelProviderHealthDetailValue(key, value) {
+	switch (key) {
+		case "closeCode":
+		case "reconnectAttempt":
+		case "statusCode": return isNonNegativeInteger(value);
+		case "providerType": return typeof value === "string" && /^[a-z][a-z0-9._-]{0,31}$/iu.test(value);
+		case "reconnecting":
+		case "sleepResumeSuspected": return typeof value === "boolean";
+	}
+	return assertNeverAgentChannelProviderHealthDetailKey(key);
+}
+function assertNeverAgentChannelProviderHealthDetailKey(key) {
+	throw new Error(`Unhandled agent channel provider health detail key: ${String(key)}`);
+}
+function isGatewayRecoveryTimeoutErrorCode(value) {
+	return value === "recovery-callback-unconfigured" || value === "recovery-timeout";
+}
+function isAgentChannelProviderHealthResultConsistent(health, result) {
+	switch (health) {
+		case "healthy":
+		case "transitioning": return result === "ok";
+		case "unhealthy-recoverable":
+		case "unhealthy-unrecoverable": return result === "failed";
+	}
+	return assertNeverAgentChannelProviderHealth(health);
+}
+function hasValidToolVmLeaseLifecycleFields(value) {
+	if (!(value.activeUseId !== void 0 || value.callerContextState !== void 0 || value.leaseRejectionReason !== void 0 || value.lifecycleEventRole !== void 0 || value.lifecycleTransition !== void 0 || value.oldLeaseId !== void 0 || value.replacementLeaseId !== void 0 || value.transitionId !== void 0)) return true;
+	if (!(optionalNonEmptyString(value.activeUseId) && optionalOneOf(toolVmLeaseCallerContextStates, value.callerContextState) && optionalOneOf(toolVmLeaseRejectionReasons, value.leaseRejectionReason) && isOneOf(toolVmLeaseLifecycleEventRoles, value.lifecycleEventRole) && isOneOf(toolVmLeaseLifecycleTransitions, value.lifecycleTransition) && typeof value.oldLeaseId === "string" && value.oldLeaseId.length > 0 && typeof value.transitionId === "string" && value.transitionId.length > 0)) return false;
+	if (isToolVmLeaseReacquiredTransition(value.lifecycleTransition)) return typeof value.replacementLeaseId === "string" && value.replacementLeaseId.length > 0;
+	return value.replacementLeaseId === void 0 && optionalOneOf(toolVmLeaseLifecycleEventRoles, value.lifecycleEventRole) && optionalOneOf(toolVmLeaseLifecycleTransitions, value.lifecycleTransition);
+}
+function isAgentVmHealthEvent(value) {
+	if (!isRecord(value) || !hasBaseEventFields(value)) return false;
+	switch (value.kind) {
+		case "caller-context-rejection": return isOneOf([
+			"lease_create",
+			"lease_get",
+			"lease_peek",
+			"lease_reacquire",
+			"lease_release",
+			"lease_renew",
+			"lease_use_end",
+			"lease_use_heartbeat",
+			"lease_use_start"
+		], value.operation) && isOneOf([
+			"caller_context_absent",
+			"caller_context_session_mismatch",
+			"caller_context_stale"
+		], value.reason) && value.result === "failed";
+		case "gateway-service-health": return typeof value.path === "string" && value.path.length > 0 && Number.isInteger(value.port) && optionalStatusCode(value.statusCode);
+		case "gateway-control-session": return optionalString(value.bootId) && optionalString(value.connectionId) && value.domain === "gateway_control" && isNonNegativeFiniteNumber(value.elapsedMs) && isOneOf(gatewayControlSessionHealthOperations, value.operation) && typeof value.peerId === "string" && value.peerId.length > 0 && optionalString(value.sessionId);
+		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) && hasValidToolVmLeaseLifecycleFields(value);
+		case "gateway-plugin-health": return isOneOf(gatewayTypeValues, value.gatewayService) && isOneOf([
+			"starting",
+			"ready",
+			"stopping",
+			"failed"
+		], value.state);
+		case "agent-channel-provider-health": return typeof value.channelProviderId === "string" && value.channelProviderId.length > 0 && isOneOf(agentChannelProviderHealthKinds, value.health) && isOneOf(agentVmHealthResultKinds, value.result) && isAgentChannelProviderHealthResultConsistent(value.health, value.result) && optionalNonNegativeInteger(value.transitionStartedAtMs) && optionalNonNegativeInteger(value.unhealthySinceMs) && isRedactedHealthDetails(value.details);
+		case "gateway-recovery":
+			if (!isOneOf([
+				"gateway-vm-cold-start",
+				"gateway-vm-restart",
+				"observe-only",
+				"operator-required"
+			], value.action) || !isNonNegativeInteger(value.consecutiveFailures) || !isPositiveInteger(value.cooldownMs) || !isNonNegativeFiniteNumber(value.elapsedMs) || !isOneOf(gatewayRecoveryHealthReasons, value.reason) || !optionalString(value.operationId)) return false;
+			if (value.result === "ok") {
+				if (value.action !== "gateway-vm-cold-start" && value.action !== "gateway-vm-restart") return false;
+				if (!(isNonNegativeInteger(value.leaseReleaseFailureCount) && typeof value.newBootedAt === "string" && isNonNegativeInteger(value.newHostPid) && typeof value.newVmId === "string" && value.errorCode === void 0)) return false;
+				if (value.action === "gateway-vm-cold-start") return value.oldBootedAt === void 0 && value.oldHostPid === void 0 && value.oldVmId === void 0;
+				return typeof value.oldBootedAt === "string" && isNonNegativeInteger(value.oldHostPid) && typeof value.oldVmId === "string";
+			}
+			if (value.result === "failed") {
+				if (typeof value.errorCode !== "string" || value.errorCode.length === 0 || !optionalNonNegativeInteger(value.leaseReleaseFailureCount) || value.newBootedAt !== void 0 || value.newHostPid !== void 0 || value.newVmId !== void 0 || !optionalString(value.operationId)) return false;
+				if (value.action === "gateway-vm-restart") {
+					if (isGatewayRecoveryTimeoutErrorCode(value.errorCode)) return optionalString(value.oldBootedAt) && optionalNonNegativeInteger(value.oldHostPid) && optionalString(value.oldVmId);
+					return optionalString(value.oldBootedAt) && optionalNonNegativeInteger(value.oldHostPid) && typeof value.oldVmId === "string" && value.oldVmId.length > 0;
+				}
+				return (value.action === "gateway-vm-cold-start" || value.action === "observe-only" || value.action === "operator-required") && value.oldBootedAt === void 0 && value.oldHostPid === void 0 && value.oldVmId === void 0;
+			}
+			return false;
+		case "gateway-recovery-suspended": return isOneOf([
+			"gateway-vm-cold-start",
+			"gateway-vm-restart",
+			"observe-only",
+			"operator-required"
+		], value.action) && isNonNegativeInteger(value.consecutiveFailedRecoveries) && isNonNegativeInteger(value.consecutiveFailures) && isPositiveInteger(value.cooldownMs) && value.errorCode === "max-failed-recoveries" && isPositiveInteger(value.failedRecoveryResetMs) && optionalString(value.operationId) && isOneOf(gatewayRecoveryHealthReasons, value.reason) && value.result === "failed";
+		default: return false;
+	}
+}
+function healthEventBucketKey(event) {
+	switch (event.kind) {
+		case "caller-context-rejection": return `${event.zoneId}:${event.kind}:${event.operation}:${event.reason}`;
+		case "gateway-control-session": return `${event.zoneId}:${event.kind}`;
+		case "gateway-service-health": return `${event.zoneId}:${event.kind}`;
+		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":
+			if (event.transitionId !== void 0) return `${event.zoneId}:${event.kind}:lifecycle:${event.transitionId}`;
+			return `${event.zoneId}:${event.kind}:${event.leaseId}:${event.operation}`;
+		case "gateway-plugin-health": return `${event.zoneId}:${event.kind}:${event.gatewayService}`;
+		case "agent-channel-provider-health": return `${event.zoneId}:${event.kind}:${event.channelProviderId}`;
+		case "gateway-recovery": return `${event.zoneId}:${event.kind}:${event.action}`;
+		case "gateway-recovery-suspended": return `${event.zoneId}:${event.kind}:${event.action}`;
+	}
+	return assertNeverHealthEvent(event);
+}
+function isHealthIssueBearingEvent(event) {
+	return event.kind !== "caller-context-rejection";
+}
+function failedIssueKindForEvent(event) {
+	switch (event.kind) {
+		case "gateway-service-health": return "gateway-service-unhealthy";
+		case "gateway-control-session": return "gateway-control-session-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";
+		case "agent-channel-provider-health": return "agent-channel-provider-unhealthy";
+		case "gateway-recovery": return "gateway-recovery-failed";
+		case "gateway-recovery-suspended": return "gateway-recovery-suspended";
+	}
+	return assertNeverHealthEvent(event);
+}
+function assertNeverHealthEvent(event) {
+	throw new Error(`Unhandled health event kind: ${JSON.stringify(event)}`);
+}
+function assertNeverAgentChannelProviderHealth(health) {
+	throw new Error(`Unhandled agent channel provider health: ${String(health)}`);
+}
+function issueForEvent(event, options) {
+	if (!isHealthIssueBearingEvent(event)) return;
+	if (options.nowMs - event.observedAtMs > options.staleAfterMs && !isNonStalingSuccessfulEvent(event)) 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 isNonStalingSuccessfulEvent(event) {
+	return event.kind === "gateway-recovery" && event.result === "ok";
+}
+function isReacquiredControllerFinalEvent(event) {
+	return event.kind === "tool-vm-ssh" && event.lifecycleEventRole === "controller_final" && isToolVmLeaseReacquiredTransition(event.lifecycleTransition) && event.result === "ok";
+}
+function latestReacquiredAtMsByOldLeaseId(events) {
+	const latestByOldLeaseId = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (!isReacquiredControllerFinalEvent(event)) continue;
+		const previousObservedAtMs = latestByOldLeaseId.get(event.oldLeaseId);
+		if (previousObservedAtMs === void 0 || previousObservedAtMs < event.observedAtMs) latestByOldLeaseId.set(event.oldLeaseId, event.observedAtMs);
+	}
+	return latestByOldLeaseId;
+}
+function isPlainToolVmSshEvent(event) {
+	return event.kind === "tool-vm-ssh" && event.transitionId === void 0;
+}
+function filterSupersededToolVmSshEvents(events) {
+	const latestReacquiredAtByOldLeaseId = latestReacquiredAtMsByOldLeaseId(events);
+	return events.filter((event) => {
+		if (!isPlainToolVmSshEvent(event)) return true;
+		const reacquiredAtMs = latestReacquiredAtByOldLeaseId.get(event.leaseId);
+		return reacquiredAtMs === void 0 || reacquiredAtMs < event.observedAtMs;
+	});
+}
+function deriveZoneHealthSnapshot(events, options) {
+	const latestByKey = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.zoneId !== options.zoneId || event.kind === "caller-context-rejection") continue;
+		const key = healthEventBucketKey(event);
+		const previous = latestByKey.get(key);
+		if (!previous || previous.observedAtMs <= event.observedAtMs) latestByKey.set(key, event);
+	}
+	const latestEvents = filterSupersededToolVmSshEvents([...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/git-read-allowlist.ts
+function trimGitSuffix(repoPath) {
+	return repoPath.replace(/\.git$/u, "");
+}
+function normalizeRepoPath(repoPath) {
+	const trimmedRepoPath = trimGitSuffix(repoPath.trim().replace(/^\/+/u, ""));
+	const segments = trimmedRepoPath.split("/");
+	if (segments.length < 2 || segments.some((segment) => !/^[A-Za-z0-9_.-]+$/u.test(segment))) return;
+	return trimmedRepoPath;
+}
+function normalizeHost(host) {
+	const normalizedHost = host.trim().toLowerCase();
+	if (!/^[a-z0-9.-]+$/u.test(normalizedHost) || normalizedHost.startsWith(".")) return;
+	return normalizedHost;
+}
+function normalizeGitRepoForSshReadAllowlist(repoUrl) {
+	const trimmedRepoUrl = repoUrl.trim();
+	if (trimmedRepoUrl.length === 0) return;
+	let parsedUrl;
+	try {
+		parsedUrl = new URL(trimmedRepoUrl);
+	} catch {
+		parsedUrl = void 0;
+	}
+	if (parsedUrl !== void 0) {
+		const host = normalizeHost(parsedUrl.hostname);
+		const repoPath = normalizeRepoPath(parsedUrl.pathname);
+		return host === void 0 || repoPath === void 0 ? void 0 : {
+			host,
+			repoPath
+		};
+	}
+	const scpMatch = /^(?:[^@]+@)?(?<host>[A-Za-z0-9.-]+):(?<repoPath>[^:]+)$/u.exec(trimmedRepoUrl);
+	if (scpMatch?.groups?.host !== void 0 && scpMatch.groups.repoPath !== void 0) {
+		const host = normalizeHost(scpMatch.groups.host);
+		const repoPath = normalizeRepoPath(scpMatch.groups.repoPath);
+		return host === void 0 || repoPath === void 0 ? void 0 : {
+			host,
+			repoPath
+		};
+	}
+	const hostPathMatch = /^(?<host>[A-Za-z0-9.-]+)\/(?<repoPath>.+)$/u.exec(trimmedRepoUrl);
+	if (hostPathMatch?.groups?.host !== void 0 && hostPathMatch.groups.repoPath !== void 0) {
+		const repoPathWithoutHost = normalizeRepoPath(hostPathMatch.groups.repoPath);
+		const host = normalizeHost(hostPathMatch.groups.host);
+		if (host !== void 0 && repoPathWithoutHost !== void 0 && host.includes(".")) return {
+			host,
+			repoPath: repoPathWithoutHost
+		};
+	}
+	const bareRepoPath = normalizeRepoPath(trimmedRepoUrl);
+	if (bareRepoPath !== void 0) return {
+		host: "github.com",
+		repoPath: bareRepoPath
+	};
+}
+function normalizeGitReposForSshReadAllowlist(repoUrls) {
+	if (repoUrls === void 0) return {
+		allowedHosts: [],
+		allowedRepos: []
+	};
+	const allowedHosts = /* @__PURE__ */ new Set();
+	const allowedRepos = /* @__PURE__ */ new Set();
+	for (const repoUrl of repoUrls) {
+		const normalizedRepo = normalizeGitRepoForSshReadAllowlist(repoUrl);
+		if (normalizedRepo !== void 0) {
+			allowedHosts.add(normalizedRepo.host);
+			allowedRepos.add(normalizedRepo.repoPath);
+		}
+	}
+	return {
+		allowedHosts: [...allowedHosts].toSorted(),
+		allowedRepos: [...allowedRepos].toSorted()
+	};
+}
+function normalizeGitHubRepoForSshReadAllowlist(repoUrl) {
+	const trimmedRepoUrl = repoUrl.trim();
+	if (trimmedRepoUrl.length === 0) return;
+	const scpMatch = /^git@github\.com:(?<repoPath>[^:]+\/[^/]+)$/iu.exec(trimmedRepoUrl);
+	if (scpMatch?.groups?.repoPath !== void 0) return normalizeRepoPath(scpMatch.groups.repoPath);
+	const hostPathMatch = /^(?:github\.com\/)(?<repoPath>[^/]+\/[^/]+)$/iu.exec(trimmedRepoUrl);
+	if (hostPathMatch?.groups?.repoPath !== void 0) return normalizeRepoPath(hostPathMatch.groups.repoPath);
+	const bareRepoPath = normalizeRepoPath(trimmedRepoUrl);
+	if (bareRepoPath !== void 0) return bareRepoPath;
+	let parsedUrl;
+	try {
+		parsedUrl = new URL(trimmedRepoUrl);
+	} catch {
+		return;
+	}
+	if (parsedUrl.hostname.toLowerCase() !== "github.com") return;
+	return normalizeRepoPath(parsedUrl.pathname);
+}
+function normalizeGitHubReposForSshReadAllowlist(repoUrls) {
+	return normalizeGitReposForSshReadAllowlist(repoUrls).allowedRepos;
+}
+//#endregion
+//#region src/force-ipv4-egress.ts
+/**
+* Canonical NODE_OPTIONS value for forcing IPv4-preference egress
+* in agent-vm VMs.
+*
+* Background: the managed VM synthetic DNS path (when tcpHosts is enabled)
+* returns a per-host IPv4 (reverse-lookable) and a single shared
+* IPv4-mapped IPv6 (::ffff:198.18.0.1, NOT reverse-lookable). Node
+* 20+'s fetch (via undici, autoSelectFamily: true) races both
+* families; when the IPv6 race wins (~5-20% under sequential load),
+* the VM egress router cannot route it and the request fails with a non-JSON
+* 400 (HTTP) or 403 (TLS). The two flags below stop the race:
+*
+*   --dns-result-order=ipv4first       changes dns.lookup() so
+*                                      IPv4 addresses are listed
+*                                      before IPv6.
+*
+*   --no-network-family-autoselection  disables Node's Happy
+*                                      Eyeballs entirely. This is
+*                                      the load-bearing flag —
+*                                      --dns-result-order alone
+*                                      doesn't prevent Node from
+*                                      racing both families if
+*                                      IPv4 is slow.
+*
+* Composition: NODE_OPTIONS is whitespace-separated. To add more
+* flags downstream, append rather than replace. Example:
+*
+*   NODE_OPTIONS: `${FORCE_IPV4_EGRESS_NODE_OPTIONS} --inspect`
+*
+* Reference: see `shravan-claw@0ddf5f2:docs/wip/debugging/
+* 2026-05-21-lease-keepalive-400-and-discord-403-ipv6-race.md`
+* for the full root-cause analysis. Node-side flag references:
+* https://github.com/nodejs/node/issues/54359 (autoSelectFamily
+* 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).
+*
+* Use this at every site where NODE_OPTIONS is set into a VM env
+* block AFTER a spread of user-controlled secrets, to guarantee
+* the forced flags are always present in the final value even if
+* 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 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.
+*
+* Examples:
+*
+*   composeNodeOptions(undefined)
+*     ──► '--dns-result-order=ipv4first --no-network-family-autoselection'
+*
+*   composeNodeOptions('')
+*     ──► '--dns-result-order=ipv4first --no-network-family-autoselection'
+*
+*   composeNodeOptions('--inspect=0.0.0.0:9229')
+*     ──► '--dns-result-order=ipv4first --no-network-family-autoselection
+*          --inspect=0.0.0.0:9229'
+*/
+function composeNodeOptions(userValue) {
+	const trimmed = userValue?.trim() ?? "";
+	if (trimmed === "") return FORCE_IPV4_EGRESS_NODE_OPTIONS;
+	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/managed-gateway-boot-contract.ts
+function assertPlainRecord(value, label) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a plain object.`);
+	const prototype = Reflect.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error(`${label} must be a plain object.`);
+}
+function assertExactFields(record, label, requiredFields) {
+	const requiredFieldSet = new Set(requiredFields);
+	for (const fieldKey of Reflect.ownKeys(record)) {
+		if (typeof fieldKey !== "string") throw new Error(`${label} has an unknown symbol field.`);
+		const fieldName = fieldKey;
+		if (!requiredFieldSet.has(fieldName)) throw new Error(`${label} has unknown field '${fieldName}'.`);
+		const descriptor = Reflect.getOwnPropertyDescriptor(record, fieldName);
+		if (descriptor === void 0 || !Object.hasOwn(descriptor, "value")) throw new Error(`${label}.${fieldName} must be a data field.`);
+	}
+	for (const fieldName of requiredFields) if (!Object.hasOwn(record, fieldName)) throw new Error(`${label} is missing required field '${fieldName}'.`);
+}
+function parseLiteral(value, expected, label) {
+	if (value !== expected) throw new Error(`${label} must be ${JSON.stringify(expected)}.`);
+	return expected;
+}
+function parseNonEmptyString(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string.`);
+	return value;
+}
+function parseAbsoluteGuestPath(value, label) {
+	const guestPath = parseNonEmptyString(value, label);
+	if (!guestPath.startsWith("/") || guestPath.includes("\0") || guestPath.includes("//") || guestPath.length > 1 && guestPath.endsWith("/") || guestPath.split("/").some((segment) => segment === "." || segment === "..")) throw new Error(`${label} must be a normalized absolute guest path.`);
+	return guestPath;
+}
+function parseHttpPath(value, label) {
+	const httpPath = parseNonEmptyString(value, label);
+	if (!httpPath.startsWith("/") || httpPath.includes("\0")) throw new Error(`${label} must be an absolute HTTP path.`);
+	return httpPath;
+}
+function parseGuestPort(value, label) {
+	if (!Number.isInteger(value) || typeof value !== "number" || value < 1 || value > 65535) throw new Error(`${label} must be an integer TCP port from 1 through 65535.`);
+	return value;
+}
+function parseLogIdentity(value, label) {
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, ["guestPath", "serviceName"]);
+	return Object.freeze({
+		guestPath: parseAbsoluteGuestPath(value.guestPath, `${label}.guestPath`),
+		serviceName: parseNonEmptyString(value.serviceName, `${label}.serviceName`)
+	});
+}
+function parseToolPortalReadiness(value, label) {
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, [
+		"evidencePath",
+		"kind",
+		"socketPath"
+	]);
+	return Object.freeze({
+		evidencePath: parseAbsoluteGuestPath(value.evidencePath, `${label}.evidencePath`),
+		kind: parseLiteral(value.kind, "tool-portal-evidence", `${label}.kind`),
+		socketPath: parseAbsoluteGuestPath(value.socketPath, `${label}.socketPath`)
+	});
+}
+function parseFrameworkReadiness(value, label) {
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, [
+		"guestPort",
+		"kind",
+		"path"
+	]);
+	return Object.freeze({
+		guestPort: parseGuestPort(value.guestPort, `${label}.guestPort`),
+		kind: parseLiteral(value.kind, "framework-http", `${label}.kind`),
+		path: parseHttpPath(value.path, `${label}.path`)
+	});
+}
+function parseFrameworkIngress(value, label) {
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, ["guestPort", "kind"]);
+	return Object.freeze({
+		guestPort: parseGuestPort(value.guestPort, `${label}.guestPort`),
+		kind: parseLiteral(value.kind, "framework-http", `${label}.kind`)
+	});
+}
+function parseToolPortalService(value) {
+	const label = "Managed Gateway boot contract toolPortalService";
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, [
+		"bootEntry",
+		"configurationInputPath",
+		"environmentInputPath",
+		"logIdentity",
+		"readiness",
+		"role"
+	]);
+	return Object.freeze({
+		bootEntry: parseLiteral(value.bootEntry, "agent-vm-gateway-runtime", `${label}.bootEntry`),
+		configurationInputPath: parseAbsoluteGuestPath(value.configurationInputPath, `${label}.configurationInputPath`),
+		environmentInputPath: parseAbsoluteGuestPath(value.environmentInputPath, `${label}.environmentInputPath`),
+		logIdentity: parseLogIdentity(value.logIdentity, `${label}.logIdentity`),
+		readiness: parseToolPortalReadiness(value.readiness, `${label}.readiness`),
+		role: parseLiteral(value.role, "tool-portal-service", `${label}.role`)
+	});
+}
+function parseFrameworkService(value) {
+	const label = "Managed Gateway boot contract frameworkService";
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, [
+		"bootEntry",
+		"configurationInputPath",
+		"environmentInputPath",
+		"framework",
+		"ingress",
+		"logIdentity",
+		"readiness",
+		"role"
+	]);
+	const framework = value.framework;
+	if (framework !== "openclaw" && framework !== "hermes") throw new Error(`${label}.framework must be "openclaw" or "hermes".`);
+	const ingress = parseFrameworkIngress(value.ingress, `${label}.ingress`);
+	const readiness = parseFrameworkReadiness(value.readiness, `${label}.readiness`);
+	if (ingress.guestPort !== readiness.guestPort) throw new Error(`${label} ingress and readiness must identify the same guest port.`);
+	const commonFields = {
+		configurationInputPath: parseAbsoluteGuestPath(value.configurationInputPath, `${label}.configurationInputPath`),
+		environmentInputPath: parseAbsoluteGuestPath(value.environmentInputPath, `${label}.environmentInputPath`),
+		ingress,
+		logIdentity: parseLogIdentity(value.logIdentity, `${label}.logIdentity`),
+		readiness,
+		role: parseLiteral(value.role, "framework-service", `${label}.role`)
+	};
+	if (framework === "openclaw") return Object.freeze({
+		...commonFields,
+		bootEntry: parseLiteral(value.bootEntry, "openclaw-gateway", `${label}.bootEntry`),
+		framework
+	});
+	return Object.freeze({
+		...commonFields,
+		bootEntry: parseLiteral(value.bootEntry, "hermes-gateway", `${label}.bootEntry`),
+		framework
+	});
+}
+/**
+* Parses untrusted or serialized boot metadata into the exact V1 contract.
+* Unknown fields are rejected at every level and a fresh deeply frozen value
+* is returned so callers cannot retain mutation authority after validation.
+*/
+function parseManagedGatewayBootContract(value) {
+	const label = "Managed Gateway boot contract";
+	assertPlainRecord(value, label);
+	assertExactFields(value, label, [
+		"contractVersion",
+		"frameworkService",
+		"kind",
+		"toolPortalService"
+	]);
+	return Object.freeze({
+		contractVersion: parseLiteral(value.contractVersion, 1, `${label}.contractVersion`),
+		frameworkService: parseFrameworkService(value.frameworkService),
+		kind: parseLiteral(value.kind, "managed-gateway-exact-two-role", `${label}.kind`),
+		toolPortalService: parseToolPortalService(value.toolPortalService)
+	});
+}
+//#endregion
+//#region src/split-resolved-gateway-secrets.ts
+function splitResolvedSecretsByInjection(secretConfigs, resolvedSecrets, options) {
+	const environmentSecrets = {};
+	const mediatedSecrets = {};
+	const logPrefix = options.logPrefix ?? "split-resolved-secrets";
+	for (const [secretName, secretValue] of Object.entries(resolvedSecrets)) {
+		const secretConfig = secretConfigs[secretName];
+		if (!secretConfig) throw new Error(`[${logPrefix}] Secret '${secretName}' was resolved but has no matching secret config.`);
+		if (!targetsAudience(secretConfig.audience, options.audience)) continue;
+		if (secretConfig.injection === "http-mediation") {
+			if (secretConfig.hosts.length === 0) throw new Error(`[${logPrefix}] Secret '${secretName}' uses http-mediation but declares no hosts.`);
+			mediatedSecrets[secretName] = {
+				hosts: [...secretConfig.hosts],
+				value: secretValue
+			};
+			continue;
+		}
+		const envSecretAudience = secretConfig.audience;
+		if (envSecretAudience !== "gateway") throw new Error(`[${logPrefix}] Secret '${secretName}' uses env injection with non-gateway audience '${envSecretAudience}'.`);
+		if (options.audience === "gateway") environmentSecrets[secretName] = secretValue;
+	}
+	return {
+		environmentSecrets,
+		mediatedSecrets
+	};
+}
+function splitResolvedGatewaySecrets(zone, resolvedSecrets) {
+	return splitResolvedSecretsByInjection(zone.secrets, resolvedSecrets, {
+		audience: "gateway",
+		logPrefix: "split-resolved-gateway-secrets"
+	});
+}
+function assertNoRuntimeSecretCollision(secretName, target, baseSecrets, runtimeSeen, logPrefix) {
+	if (runtimeSeen.has(secretName)) throw new Error(`[${logPrefix}] Runtime gateway secret '${secretName}' is declared for both environment and http-mediation injection.`);
+	if (secretName in baseSecrets.environmentSecrets) throw new Error(`[${logPrefix}] Runtime gateway ${target} secret '${secretName}' would overwrite an authored environment secret.`);
+	if (secretName in baseSecrets.mediatedSecrets) throw new Error(`[${logPrefix}] Runtime gateway ${target} secret '${secretName}' would overwrite an authored http-mediation secret.`);
+	runtimeSeen.add(secretName);
+}
+function mergeRuntimeGatewaySecrets(baseSecrets, options = {}) {
+	const logPrefix = options.logPrefix ?? "merge-runtime-gateway-secrets";
+	const runtimeSeen = /* @__PURE__ */ new Set();
+	for (const secretName of Object.keys(options.runtimeEnvironment ?? {})) assertNoRuntimeSecretCollision(secretName, "environment", baseSecrets, runtimeSeen, logPrefix);
+	for (const secretName of Object.keys(options.runtimeMediatedSecrets ?? {})) assertNoRuntimeSecretCollision(secretName, "http-mediation", baseSecrets, runtimeSeen, logPrefix);
+	return {
+		environmentSecrets: {
+			...baseSecrets.environmentSecrets,
+			...options.runtimeEnvironment
+		},
+		mediatedSecrets: {
+			...baseSecrets.mediatedSecrets,
+			...options.runtimeMediatedSecrets
+		}
+	};
+}
+//#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();
+}
+function isToolVmActiveUseId(value) {
+	return validate(value) && version(value) === 7;
+}
+function normalizeToolVmActiveUseCorrelation(correlation) {
+	if (!isToolVmActiveUseCorrelationRecord(correlation)) return;
+	const getString = (key) => {
+		const value = correlation[key];
+		return typeof value === "string" && value.length > 0 ? value : void 0;
+	};
+	const normalizedCorrelation = {
+		...getString("messageId") !== void 0 ? { messageId: getString("messageId") } : {},
+		...getString("requestId") !== void 0 ? { requestId: getString("requestId") } : {},
+		...getString("runId") !== void 0 ? { runId: getString("runId") } : {},
+		...getString("sessionKeyDigest") !== void 0 ? { sessionKeyDigest: getString("sessionKeyDigest") } : {},
+		...getString("toolCallId") !== void 0 ? { toolCallId: getString("toolCallId") } : {},
+		...getString("traceId") !== void 0 ? { traceId: getString("traceId") } : {}
+	};
+	return Object.keys(normalizedCorrelation).length > 0 ? normalizedCorrelation : void 0;
+}
+function isToolVmActiveUseCorrelationRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function createToolVmActiveUseHandle(options) {
+	const useId = createToolVmActiveUseId();
+	const startedUse = await options.startActiveUse({
+		...options.correlation ? { correlation: options.correlation } : {},
+		useId
+	});
+	const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+	const clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+	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);
+			heartbeatTimer = void 0;
+		}
+	};
+	const scheduleHeartbeat = (delayMs) => {
+		if (now() - startedAt >= maxHeartbeatDurationMs) return;
+		clearHeartbeatTimer();
+		heartbeatTimer = setTimeoutImpl(() => {
+			if (now() - startedAt >= maxHeartbeatDurationMs) return;
+			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);
+			});
+		}, jitterDelayMs({
+			delayMs,
+			jitterRatio: heartbeatJitterRatio,
+			random
+		}));
+	};
+	scheduleHeartbeat(startedUse.heartbeatAfterMs);
+	const end = async (outcome = "completed") => {
+		if (ended) return;
+		ended = true;
+		clearHeartbeatTimer();
+		try {
+			await options.endActiveUse(startedUse.useId, {
+				outcome,
+				...latestReport === void 0 ? {} : { report: latestReport }
+			});
+		} catch (error) {
+			if (options.isEndErrorTolerable?.(error) === true) {
+				options.logEndFailure?.(error);
+				return;
+			}
+			throw error;
+		}
+	};
+	return {
+		signal: operationAbortController.signal,
+		useId: startedUse.useId,
+		dispose: end,
+		end,
+		report: (report) => {
+			if (ended) return;
+			latestReport = report;
+		}
+	};
+}
+//#endregion
+//#region src/runtime-paths/runtime-path-mapping.ts
+const TOOL_VM_SCRATCH_GUEST_ROOT = "/scratch";
+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([
+	"host",
+	"port",
+	"user"
+]);
+function objectValue$1(value) {
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isVmCapabilityLease(value, transport) {
+	const record = objectValue$1(value);
+	return record !== void 0 && typeof Reflect.get(record, "leaseId") === "string" && Reflect.get(record, "transport") === transport;
+}
+function isVmSshEndpoint(value) {
+	const record = objectValue$1(value);
+	return record !== void 0 && typeof Reflect.get(record, "host") === "string" && isNonEmptyString(Reflect.get(record, "identityPem")) && isNonEmptyString(Reflect.get(record, "knownHostsLine")) && typeof Reflect.get(record, "port") === "number" && typeof Reflect.get(record, "user") === "string";
+}
+function isVmSshPublicEndpoint(value) {
+	const record = objectValue$1(value);
+	if (record === void 0) return false;
+	for (const key of Object.keys(record)) if (!VM_SSH_PUBLIC_ENDPOINT_KEYS.has(key)) return false;
+	return typeof Reflect.get(record, "host") === "string" && typeof Reflect.get(record, "port") === "number" && typeof Reflect.get(record, "user") === "string";
+}
+//#endregion
+//#region src/tool-vm-lease.ts
+const defaultToolVmLeaseAuthorityTombstoneTtlMs = 600 * 1e3;
+const TOOL_VM_WORK_GUEST_ROOT = "/work";
+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") && 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") && 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 { ControllerRequestPolicyTransportError, FORCE_IPV4_EGRESS_NODE_OPTIONS, GATEWAY_CONTROL_CALLER_CONTEXT_AGENT_AUTHORITY_KEYS_ENV, GATEWAY_CONTROL_CALLER_CONTEXT_PROOF_KEY_ENV, GATEWAY_CONTROL_PRIVATE_ENVIRONMENT_NAMES, OPENCLAW_STATE_SANDBOXES_VM_ROOT, OPENCLAW_STATE_VM_ROOT, TOOL_VM_SCRATCH_GUEST_ROOT, TOOL_VM_WORK_GUEST_ROOT, agentVmHealthEventKinds, agentVmHealthResultKinds, buildGatewaySessionLabel, buildToolSessionLabel, composeNodeOptions, controllerRequestPolicies, controllerVmHost, createGatewayTelemetryProducerSafetyContract, createToolVmActiveUseHandle, createToolVmActiveUseId, createToolVmLeaseId, createWebSocketUpgradeRequestGuard, defaultToolVmLeaseAuthorityTombstoneTtlMs, deriveZoneHealthSnapshot, drainControllerResponseBody, egressHostsForAudience, externalControllerRoutes, gatewayControlSessionHealthOperations, gatewayFrameworkTelemetryServiceNames, gatewayRecoveryHealthReasons, gatewayTelemetryAdmissionLimits, gatewayTelemetrySourcePolicy, gatewayToolPortalTelemetryServiceName, gatewayTypeValues, gatewayVmAllowedHosts, genericControllerRequestEventOperations, healthEventBucketKey, isAgentVmHealthEvent, isToolVmActiveUseId, isToolVmLeaseId, isToolVmLeasePeek, isToolVmSshLease, isVmCapabilityLease, isVmSshEndpoint, isVmSshPublicEndpoint, mergeRuntimeGatewaySecrets, normalizeGitHubRepoForSshReadAllowlist, normalizeGitHubReposForSshReadAllowlist, normalizeGitRepoForSshReadAllowlist, normalizeGitReposForSshReadAllowlist, normalizeToolVmActiveUseCorrelation, parseManagedGatewayBootContract, parseToolVmLeaseId, splitResolvedGatewaySecrets, splitResolvedSecretsByInjection, targetsAudience, translateRuntimePath, vmAudienceValues, websocketUpgradesForAudience, workerVmAllowedHosts, zoneHealthIssueKinds, zoneHealthStateKinds };
+
+//# sourceMappingURL=index.js.map