@viewportai/daemon 0.27.0 → 0.29.0

package/dist/cli/worker-runtime.js

@@ -1,7 +1,10 @@
 import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 import { constants as fsConstants } from 'node:fs';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { WebSocket } from 'ws';
 import YAML from 'yaml';
 import { ConfigManager } from '../core/config.js';
 import { Daemon } from '../core/daemon.js';
@@ -13,6 +16,43 @@ import { WorkflowRunStore } from '../workflows/store.js';
 import { transportFetch } from './network.js';
 import { acquireWorkerProcessLock } from './worker-process-lock.js';
 import { readWorkerPairingRecord, workerProfileIntegrity, } from './worker-profile.js';
+function runtimeContextTargetIdValue(primary, fallback) {
+    return stringValue(primary?.['runtime_context_target_id'] ??
+        primary?.['runtimeContextTargetId'] ??
+        primary?.['runtime_target_id'] ??
+        primary?.['runtimeTargetId'] ??
+        fallback?.['runtime_context_target_id'] ??
+        fallback?.['runtimeContextTargetId'] ??
+        fallback?.['runtime_target_id'] ??
+        fallback?.['runtimeTargetId']);
+}
+function hostedRuntimeContextTargetId(profile, lease) {
+    return (lease.runtimeTargetId ??
+        (profile.managedExecutorId ? `managed_executor:${profile.managedExecutorId}` : undefined));
+}
+function hostedWorkflowInputs(profile, lease) {
+    const base = { ...(lease.inputSnapshot ?? {}) };
+    const runtimeTargetId = hostedRuntimeContextTargetId(profile, lease);
+    if (!profile.serverUrl ||
+        !profile.workspaceId ||
+        !lease.assignmentClaimToken ||
+        !runtimeTargetId) {
+        return Object.keys(base).length > 0 ? base : undefined;
+    }
+    const viewport = isWorkflowInputRecord(base['viewport']) ? { ...base['viewport'] } : {};
+    viewport['runtimeContextTarget'] = {
+        schema: 'viewport.runtime_context_target/v1',
+        serverUrl: profile.serverUrl,
+        workspaceId: profile.workspaceId,
+        runtimeTargetId,
+        credential: lease.assignmentClaimToken,
+    };
+    base['viewport'] = viewport;
+    return base;
+}
+function isWorkflowInputRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
 class HttpPollingTransport {
     profile;
     mode;
@@ -39,9 +79,145 @@ class HttpPollingTransport {
         return fetchHostedAssignmentHttp(this.profile, lease);
     }
 }
+class RelayWorkerTransport {
+    profile;
+    mode = 'relay';
+    ws = null;
+    pending = new Map();
+    constructor(profile) {
+        this.profile = profile;
+    }
+    async claim(body) {
+        return claimLeaseHttp(this.profile, body, (request) => this.dispatchHostedManagedExecutorRequest(request));
+    }
+    async heartbeat(options) {
+        return heartbeatHttp(this.profile, {
+            ...options,
+            transport: 'relay',
+        }, (request) => this.dispatchHostedManagedExecutorRequest(request));
+    }
+    async sync(lease, execution) {
+        return syncLeaseHttp(this.profile, lease, execution, (request) => this.dispatchHostedManagedExecutorRequest(request));
+    }
+    async cleanup(lease) {
+        return cleanupLeaseHttp(this.profile, lease);
+    }
+    async pollRuntimeCommands(lease) {
+        return fetchHostedAssignmentHttp(this.profile, lease, (request) => this.dispatchHostedManagedExecutorRequest(request));
+    }
+    async dispatchHostedManagedExecutorRequest(request) {
+        const ws = await this.connection();
+        const requestId = crypto.randomUUID();
+        const frame = {
+            type: 'viewport.worker_transport.request/v1',
+            requestId,
+            method: request.method,
+            path: request.requestPath,
+            headers: request.headers,
+            body: request.serialized,
+        };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(requestId);
+                reject(new Error(`Relay worker transport request ${request.path} timed out.`));
+            }, relayWorkerRequestTimeoutMs());
+            this.pending.set(requestId, { resolve, reject, timeout });
+            ws.send(JSON.stringify(frame), (error) => {
+                if (error) {
+                    clearTimeout(timeout);
+                    this.pending.delete(requestId);
+                    reject(error);
+                }
+            });
+        });
+    }
+    async connection() {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            return this.ws;
+        }
+        if (!isHostedManagedExecutorProfile(this.profile)) {
+            throw new Error('Relay worker transport requires a hosted managed executor profile.');
+        }
+        const tokenResponse = await hostedManagedExecutorFetch(this.profile, 'POST', 'relay-token', {
+            credential: this.profile.credential,
+            ttl_seconds: 3600,
+        });
+        const tokenPayload = (await tokenResponse.json());
+        const token = stringValue(tokenPayload['relayToken']);
+        const claims = recordValue(tokenPayload['claims']);
+        const claimRelayWsBaseUrl = stringValue(claims?.['relayWsBaseUrl']);
+        if (!token) {
+            throw new Error('Relay worker transport token response did not include a relay token.');
+        }
+        const relayWsBaseUrl = this.profile.relayWsBaseUrl ??
+            process.env['VIEWPORT_RELAY_WS_BASE_URL'] ??
+            process.env['VPD_RELAY_WS_BASE_URL'] ??
+            claimRelayWsBaseUrl ??
+            relayWsBaseUrlFromServerUrl(this.profile.serverUrl);
+        const url = new URL(relayWsBaseUrl);
+        url.searchParams.set('role', 'worker');
+        url.searchParams.set('workspaceId', this.profile.workspaceId);
+        const ws = new WebSocket(url, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => reject(new Error('Relay worker transport connection timed out.')), relayWorkerConnectionTimeoutMs());
+            ws.once('open', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            ws.once('error', (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            });
+        });
+        ws.on('message', (raw) => {
+            this.handleMessage(raw.toString('utf8'));
+        });
+        ws.on('close', () => {
+            for (const [requestId, pending] of this.pending.entries()) {
+                clearTimeout(pending.timeout);
+                pending.reject(new Error('Relay worker transport connection closed.'));
+                this.pending.delete(requestId);
+            }
+            this.ws = null;
+        });
+        this.ws = ws;
+        return ws;
+    }
+    handleMessage(text) {
+        let frame;
+        try {
+            const parsed = JSON.parse(text);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return;
+            frame = parsed;
+        }
+        catch {
+            return;
+        }
+        if (frame['type'] !== 'viewport.worker_transport.response/v1')
+            return;
+        const requestId = stringValue(frame['requestId']);
+        if (!requestId)
+            return;
+        const pending = this.pending.get(requestId);
+        if (!pending)
+            return;
+        this.pending.delete(requestId);
+        clearTimeout(pending.timeout);
+        const status = typeof frame['status'] === 'number' ? frame['status'] : 502;
+        const headers = recordValue(frame['headers']);
+        const body = typeof frame['body'] === 'string' ? frame['body'] : '';
+        const responseBody = status === 204 || status === 205 || status === 304 ? null : body;
+        pending.resolve(new Response(responseBody, { status, headers }));
+    }
+}
 const DEFAULT_HOSTED_LEASE_SECONDS = 1_800;
 export async function runStandaloneWorker(options) {
-    const bootstrap = await loadWorkerRuntimeBootstrap(options.bootstrapPath);
+    const bootstrap = await loadWorkerRuntimeBootstrap(options.bootstrapPath, options.registrationProfilePath);
     const profile = bootstrap.profile;
     let processLock = null;
     try {
@@ -50,10 +226,9 @@ export async function runStandaloneWorker(options) {
         if (transport === 'inbound') {
             validateInboundWorkerGate(profile);
         }
-        if (transport === 'relay') {
-            throw new Error('Relay worker transport is not supported by the standalone runtime yet.');
-        }
-        const workerTransport = new HttpPollingTransport(profile, transport);
+        const workerTransport = transport === 'relay'
+            ? new RelayWorkerTransport(profile)
+            : new HttpPollingTransport(profile, transport);
         processLock =
             options.lifecycle === 'persistent' && !options.once
                 ? acquireWorkerProcessLock({
@@ -80,10 +255,8 @@ export async function runStandaloneWorker(options) {
             return result;
         }
         if (options.leaseToken) {
-            const lease = { id: options.leaseToken, leaseToken: options.leaseToken };
-            await workerTransport.sync(lease, { status: 'completed' });
-            await workerTransport.cleanup(lease);
-            return { claimed: 1, completed: 1, blocked: 0, failed: 0, cleanup: 1, denied: 0 };
+            throw new Error('`vpd worker run-once --lease` no longer fabricates a completed sync (EXEC-01). ' +
+                'Use `vpd worker run-once --bootstrap <file>` to execute the leased work.');
         }
         const result = {
             claimed: 0,
@@ -129,6 +302,7 @@ export async function runStandaloneWorker(options) {
                 else {
                     await workerTransport.sync(lease, execution);
                 }
+                await maybeExecuteHostedSessionVerification(profile, workerTransport, lease, execution);
                 if (execution.status === 'completed') {
                     result.completed += 1;
                 }
@@ -161,6 +335,7 @@ export async function runStandaloneWorker(options) {
 async function executeBootstrapLease(profile, transport, lease) {
     const execution = await executeClaim(profile, transport, lease);
     await transport.sync(lease, execution);
+    await maybeExecuteHostedSessionVerification(profile, transport, lease, execution);
     await transport.cleanup(lease);
     return {
         claimed: 1,
@@ -198,14 +373,209 @@ async function executeClaim(profile, transport, lease) {
     if (!isHostedManagedExecutorProfile(profile)) {
         return { status: 'completed' };
     }
-    return executeHostedWorkflowClaim(profile, transport, lease);
+    return withGatewayLeaseProcessEnv(lease, () => executeHostedWorkflowClaim(profile, transport, lease));
 }
-async function loadWorkerRuntimeBootstrap(bootstrapPath) {
+async function loadWorkerRuntimeBootstrap(bootstrapPath, registrationProfilePath) {
     if (bootstrapPath) {
         return loadSandboxBootstrap(bootstrapPath);
     }
+    if (registrationProfilePath) {
+        return {
+            profile: await loadManagedExecutorRuntimeProfile(registrationProfilePath),
+        };
+    }
     return { profile: await loadWorkerRuntimeProfile() };
 }
+async function loadManagedExecutorRuntimeProfile(profilePath) {
+    const profile = await readManagedExecutorRegistrationProfile(profilePath);
+    const credential = await credentialFromManagedExecutorProfile(profile);
+    const missing = [];
+    if (!profile.serverUrl)
+        missing.push('server URL');
+    if (!profile.workspaceId)
+        missing.push('workspace id');
+    if (!profile.executorId)
+        missing.push('managed executor id');
+    if (!credential)
+        missing.push('managed executor credential');
+    if (missing.length > 0) {
+        throw new Error(`Managed executor registration profile is missing ${missing.join(', ')}.`);
+    }
+    const identity = await ensureManagedExecutorIdentity(profile.identityKeyPath ??
+        managedExecutorIdentityPath(profile.workspaceId, profile.executorId));
+    const workspaceRoot = managedExecutorWorkspaceRoot(profile);
+    await fs.mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+    const runnerPool = stringValue(profile.capabilities?.['runner_pool']) ??
+        stringValue(profile.capabilities?.['runnerPool']) ??
+        profile.runnerProfile;
+    const capabilities = {
+        ...(profile.capabilities ?? {}),
+        ...(runnerPool ? { runner_pool: runnerPool } : {}),
+        ...(profile.runnerPosture ? { runner_posture: profile.runnerPosture } : {}),
+    };
+    return {
+        serverUrl: profile.serverUrl.replace(/\/+$/, ''),
+        serverId: profile.serverId,
+        lifecycle: 'persistent',
+        transport: workerTransportValue(profile.accessMode) ?? 'polling',
+        workspaceId: profile.workspaceId,
+        managedExecutorId: profile.executorId,
+        credential: credential,
+        workspaceRoot,
+        identityKeyPath: identity.path,
+        publicKeyFingerprint: identity.publicKeyFingerprint,
+        capabilities,
+    };
+}
+async function readManagedExecutorRegistrationProfile(profilePath) {
+    const resolved = resolveProfilePath(profilePath);
+    const parsed = JSON.parse(await fs.readFile(resolved, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Managed executor registration profile is not a JSON object: ${resolved}`);
+    }
+    const record = parsed;
+    const schema = stringValue(record['schema']);
+    if (schema && schema !== 'viewport.managed_executor_registration/v1') {
+        throw new Error(`Unsupported managed executor registration profile schema: ${schema}`);
+    }
+    const daemon = recordValue(record['daemon']);
+    const worker = recordValue(daemon?.['worker']);
+    return {
+        serverUrl: stringValue(record['server_url']) ??
+            stringValue(record['serverUrl']) ??
+            stringValue(worker?.['serverUrl']) ??
+            stringValue(worker?.['server_url']),
+        serverId: stringValue(record['server_id']) ??
+            stringValue(record['serverId']) ??
+            stringValue(record['control_plane_id']) ??
+            stringValue(worker?.['serverId']) ??
+            stringValue(worker?.['server_id']) ??
+            stringValue(worker?.['control_plane_id']),
+        workspaceId: stringValue(record['workspace_id']) ??
+            stringValue(record['workspaceId']) ??
+            stringValue(worker?.['workspaceId']) ??
+            stringValue(worker?.['workspace_id']),
+        executorId: stringValue(record['managed_executor_id']) ??
+            stringValue(record['executor_id']) ??
+            stringValue(record['executorId']) ??
+            stringValue(worker?.['managedExecutorId']) ??
+            stringValue(worker?.['managed_executor_id']),
+        credential: stringValue(record['credential']) ?? stringValue(worker?.['credential']),
+        credentialFile: stringValue(record['credential_file']) ??
+            stringValue(record['credentialFile']) ??
+            stringValue(worker?.['credentialFile']) ??
+            stringValue(worker?.['credential_file']),
+        accessMode: stringValue(record['access_mode']) ??
+            stringValue(record['accessMode']) ??
+            stringValue(worker?.['accessMode']) ??
+            stringValue(worker?.['access_mode']) ??
+            stringValue(worker?.['transport']),
+        runnerProfile: stringValue(record['runner_profile']) ??
+            stringValue(record['runnerProfile']) ??
+            stringValue(worker?.['runnerProfile']) ??
+            stringValue(worker?.['runner_profile']),
+        runnerPosture: recordValue(record['runner_posture']) ??
+            recordValue(record['runnerPosture']) ??
+            recordValue(worker?.['runnerPosture']) ??
+            recordValue(worker?.['runner_posture']) ??
+            undefined,
+        workspaceRoot: stringValue(record['workspace_root']) ??
+            stringValue(record['workspaceRoot']) ??
+            stringValue(record['workdir']) ??
+            stringValue(worker?.['workspaceRoot']) ??
+            stringValue(worker?.['workspace_root']) ??
+            stringValue(worker?.['workdir']),
+        identityKeyPath: stringValue(record['identity_key_path']) ??
+            stringValue(record['identityKeyPath']) ??
+            stringValue(worker?.['identityKeyPath']) ??
+            stringValue(worker?.['identity_key_path']),
+        capabilities: recordValue(record['capabilities']) ?? recordValue(worker?.['capabilities']) ?? undefined,
+    };
+}
+async function credentialFromManagedExecutorProfile(profile) {
+    if (profile.credentialFile) {
+        const value = (await fs.readFile(resolveProfilePath(profile.credentialFile), 'utf8')).trim();
+        if (!value) {
+            throw new Error(`Managed executor credential file is empty: ${resolveProfilePath(profile.credentialFile)}`);
+        }
+        return value;
+    }
+    return (profile.credential ??
+        process.env['VIEWPORT_MANAGED_EXECUTOR_TOKEN'] ??
+        process.env['VPD_MANAGED_EXECUTOR_TOKEN']);
+}
+function managedExecutorWorkspaceRoot(profile) {
+    if (profile.workspaceRoot)
+        return path.resolve(resolveProfilePath(profile.workspaceRoot));
+    const safeName = `${safeFilename(profile.workspaceId ?? 'workspace')}-${safeFilename(profile.executorId ?? 'executor')}`;
+    return path.join(os.homedir(), '.viewport', 'managed-executors', 'workspaces', safeName);
+}
+function managedExecutorIdentityPath(workspaceId, executorId) {
+    const safeName = `${safeFilename(workspaceId)}-${safeFilename(executorId)}.json`;
+    return path.join(os.homedir(), '.viewport', 'managed-executors', 'identities', safeName);
+}
+async function ensureManagedExecutorIdentity(identityPath) {
+    const resolved = resolveProfilePath(identityPath);
+    try {
+        const parsed = JSON.parse(await fs.readFile(resolved, 'utf8'));
+        if (parsed.algorithm?.toLowerCase() === 'ed25519' &&
+            typeof parsed.publicKey === 'string' &&
+            typeof parsed.privateKey === 'string') {
+            return {
+                publicKey: parsed.publicKey,
+                privateKey: parsed.privateKey,
+                publicKeyFingerprint: normalizeWorkerFingerprint(parsed.publicKeyFingerprint) ??
+                    publicKeyFingerprint(parsed.publicKey),
+                path: resolved,
+            };
+        }
+    }
+    catch {
+        // Generate below.
+    }
+    const pair = crypto.generateKeyPairSync('ed25519');
+    const publicKey = pair.publicKey.export({ format: 'pem', type: 'spki' }).toString();
+    const privateKey = pair.privateKey.export({ format: 'pem', type: 'pkcs8' }).toString();
+    const record = {
+        version: 1,
+        algorithm: 'ed25519',
+        publicKey,
+        privateKey,
+        publicKeyFingerprint: publicKeyFingerprint(publicKey),
+        createdAt: new Date().toISOString(),
+    };
+    await fs.mkdir(path.dirname(resolved), { recursive: true, mode: 0o700 });
+    await fs.writeFile(resolved, `${JSON.stringify(record, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    await fs.chmod(resolved, 0o600);
+    return { ...record, path: resolved };
+}
+function publicKeyFingerprint(publicKeyPem) {
+    const key = crypto.createPublicKey(publicKeyPem);
+    const der = key.export({ format: 'der', type: 'spki' });
+    return crypto.createHash('sha256').update(der).digest('hex');
+}
+function normalizeWorkerFingerprint(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/^sha256:/, '');
+    return /^[a-f0-9]{64}$/.test(normalized) ? normalized : undefined;
+}
+function resolveProfilePath(profilePath) {
+    if (profilePath === '~')
+        return os.homedir();
+    if (profilePath.startsWith('~/'))
+        return path.join(os.homedir(), profilePath.slice(2));
+    return path.resolve(profilePath);
+}
+function safeFilename(value) {
+    return value.replace(/[^a-z0-9._-]+/gi, '_').replace(/^_+|_+$/g, '') || 'default';
+}
 async function loadWorkerRuntimeProfile() {
     const manager = new ConfigManager();
     await manager.load();
@@ -236,6 +606,7 @@ async function loadWorkerRuntimeProfile() {
         credential: worker.credential ??
             process.env['VIEWPORT_MANAGED_EXECUTOR_TOKEN'] ??
             process.env['VPD_MANAGED_EXECUTOR_TOKEN'],
+        relayWsBaseUrl: process.env['VIEWPORT_RELAY_WS_BASE_URL'] ?? process.env['VPD_RELAY_WS_BASE_URL'],
         workspaceRoot: worker.workspaceRoot,
         identityKeyPath: worker.identityKeyPath,
         publicKeyFingerprint: worker.publicKeyFingerprint,
@@ -258,6 +629,7 @@ async function loadSandboxBootstrap(bootstrapPath) {
         workspaceId: requiredString(raw['workspace_id'] ?? raw['workspaceId'], 'workspace_id'),
         managedExecutorId: requiredString(raw['executor_id'] ?? raw['executorId'], 'executor_id'),
         credential: requiredString(raw['credential'], 'credential'),
+        relayWsBaseUrl: stringValue(raw['relay_ws_base_url'] ?? raw['relayWsBaseUrl'] ?? raw['relay_url'] ?? raw['relayUrl']),
         workspaceRoot,
         identityKeyPath: identityFile.path,
         publicKeyFingerprint: identityFile.publicKeyFingerprint,
@@ -279,10 +651,13 @@ function claimedLeaseFromBootstrap(rawLease) {
     const id = requiredString(rawLease['id'] ?? rawLease['lease_id'] ?? rawLease['leaseId'], 'lease.id');
     return {
         id,
+        agentSessionId: stringValue(rawLease['agent_session_id'] ?? rawLease['agentSessionId']),
         runId: stringValue(rawLease['workflow_run_id'] ?? rawLease['run_id'] ?? rawLease['runId']),
         runtimeRunId: stringValue(rawLease['runtime_run_id'] ?? rawLease['runtimeRunId']),
         leaseToken: stringValue(rawLease['lease_token'] ?? rawLease['leaseToken']),
         assignmentClaimToken: stringValue(rawLease['assignment_claim_token'] ?? rawLease['assignmentClaimToken']),
+        sessionVerificationContract: sessionVerificationContractValue(rawLease['session_verification_contract'] ?? rawLease['sessionVerificationContract']),
+        gateway: gatewayLeaseValue(rawLease['gateway'] ?? rawLease['gatewayLease']),
         yamlSnapshot: stringValue(rawLease['yaml_snapshot'] ?? rawLease['yamlSnapshot']),
         sourceRef: stringValue(rawLease['source_ref'] ?? rawLease['sourceRef']),
         directoryPath: stringValue(rawLease['directory_path'] ?? rawLease['directoryPath']),
@@ -291,10 +666,102 @@ function claimedLeaseFromBootstrap(rawLease) {
         workflowAuthorityContract: recordValue(rawLease['workflow_authority_contract'] ?? rawLease['workflowAuthorityContract']),
         executionProfileSnapshot: recordValue(rawLease['execution_profile_snapshot'] ?? rawLease['executionProfileSnapshot']),
         workflowSnapshot: recordValue(rawLease['workflow_snapshot'] ?? rawLease['workflowSnapshot']),
-        runtimeTargetId: stringValue(rawLease['runtime_target_id'] ?? rawLease['runtimeTargetId']),
+        runtimeTargetId: runtimeContextTargetIdValue(rawLease),
         dataCapturePolicy: dataCapturePolicyValue(rawLease['data_capture_policy'] ?? rawLease['dataCapturePolicy']),
     };
 }
+function gatewayLeaseValue(value) {
+    const record = recordValue(value);
+    if (!record)
+        return undefined;
+    const provider = stringValue(record['provider']);
+    if (provider !== 'anthropic' && provider !== 'openai' && provider !== 'gemini') {
+        return undefined;
+    }
+    const gatewayBaseUrl = stringValue(record['gateway_base_url'] ??
+        record['gatewayBaseUrl'] ??
+        record['base_url'] ??
+        record['baseUrl']);
+    const virtualKey = recordValue(record['virtual_key'] ?? record['virtualKey']);
+    const token = stringValue(virtualKey?.['token']);
+    const modelAllow = arrayOfStrings(record['model_allow'] ?? record['modelAllow']);
+    if (!gatewayBaseUrl || !token || modelAllow.length === 0) {
+        return undefined;
+    }
+    return {
+        gatewayBaseUrl: gatewayBaseUrl.replace(/\/+$/, ''),
+        provider,
+        modelAllow,
+        virtualKey: { token },
+    };
+}
+async function withGatewayLeaseProcessEnv(lease, callback) {
+    const env = gatewayLeaseEnv(lease.gateway);
+    const previous = new Map();
+    for (const [key, value] of Object.entries(env)) {
+        previous.set(key, process.env[key]);
+        process.env[key] = value;
+    }
+    try {
+        return await callback();
+    }
+    finally {
+        for (const [key, value] of previous.entries()) {
+            if (value === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = value;
+            }
+        }
+    }
+}
+function gatewayLeaseEnv(gateway) {
+    if (!gateway)
+        return {};
+    const model = gateway.modelAllow[0] ?? '';
+    const base = gateway.gatewayBaseUrl.replace(/\/+$/, '');
+    const common = {
+        VIEWPORT_GATEWAY_BASE_URL: base,
+        VIEWPORT_LLM_PROVIDER: gateway.provider,
+        VIEWPORT_LLM_MODEL: model,
+        VIEWPORT_LLM_VIRTUAL_KEY: gateway.virtualKey.token,
+    };
+    if (gateway.provider === 'openai') {
+        return {
+            ...common,
+            CODEX_API_KEY: gateway.virtualKey.token,
+            OPENAI_API_KEY: gateway.virtualKey.token,
+            OPENAI_BASE_URL: `${base}/openai/v1`,
+        };
+    }
+    if (gateway.provider === 'anthropic') {
+        return {
+            ...common,
+            ANTHROPIC_API_KEY: gateway.virtualKey.token,
+            ANTHROPIC_BASE_URL: `${base}/anthropic`,
+            // Claude Code defaults to its own preferred model; the lease's model
+            // allow-list is the governed truth, so make its head the agent default.
+            ...(model ? { ANTHROPIC_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model } : {}),
+        };
+    }
+    return {
+        ...common,
+        GEMINI_API_KEY: gateway.virtualKey.token,
+        GEMINI_BASE_URL: `${base}/gemini/v1beta/openai`,
+        GOOGLE_GENERATIVE_AI_API_KEY: gateway.virtualKey.token,
+    };
+}
+function gatewayLeaseCredentialEnv(gateway) {
+    if (!gateway)
+        return {};
+    const env = gatewayLeaseEnv(gateway);
+    const aliases = {};
+    for (const [name, value] of Object.entries(env)) {
+        aliases[envNameForCredentialRef(name)] = value;
+    }
+    return aliases;
+}
 async function materializeBootstrapIdentity(identity, workspaceRoot) {
     if (!identity) {
         throw new Error('Sandbox bootstrap file is missing identity.');
@@ -336,13 +803,13 @@ function validateInboundWorkerGate(profile) {
     }
     throw new Error('Inbound worker transport listener is not implemented yet; do not enable inbound without the signed listener proof.');
 }
-async function claimLeaseHttp(profile, body) {
+async function claimLeaseHttp(profile, body, dispatcher) {
     const leaseSeconds = positiveInteger(body['leaseSeconds']) ?? DEFAULT_HOSTED_LEASE_SECONDS;
     const response = isHostedManagedExecutorProfile(profile)
         ? await hostedManagedExecutorFetch(profile, 'POST', 'claim', {
             credential: profile.credential,
             lease_seconds: leaseSeconds,
-        })
+        }, undefined, undefined, [], dispatcher)
         : await workerFetch(profile, 'workers/claim', body);
     if (response.status === 204)
         return null;
@@ -361,10 +828,18 @@ async function claimLeaseHttp(profile, body) {
     }
     return {
         id,
+        agentSessionId: stringValue(data['agent_session_id'] ??
+            data['agentSessionId'] ??
+            rawLease['agent_session_id'] ??
+            rawLease['agentSessionId']),
         runId: stringValue(data['id'] ?? rawLease['workflow_run_id'] ?? rawLease['run_id'] ?? rawLease['runId']),
         runtimeRunId: stringValue(data['runtime_run_id'] ?? rawLease['runtime_run_id']),
         leaseToken: stringValue(rawLease['lease_token'] ?? rawLease['leaseToken']),
         assignmentClaimToken: stringValue(data['assignment_claim_token']),
+        sessionVerificationContract: sessionVerificationContractValue(data['session_verification_contract'] ??
+            data['sessionVerificationContract'] ??
+            rawLease['session_verification_contract'] ??
+            rawLease['sessionVerificationContract']),
         yamlSnapshot: stringValue(data['yaml_snapshot'] ?? rawLease['yaml_snapshot']),
         sourceRef: stringValue(data['source_ref'] ?? rawLease['source_ref']),
         directoryPath: stringValue(data['directory_path'] ?? rawLease['directory_path']),
@@ -373,11 +848,11 @@ async function claimLeaseHttp(profile, body) {
         workflowAuthorityContract: recordValue(data['workflow_authority_contract'] ?? rawLease['workflow_authority_contract']),
         executionProfileSnapshot: recordValue(data['execution_profile_snapshot'] ?? rawLease['execution_profile_snapshot']),
         workflowSnapshot: recordValue(data['workflow_snapshot'] ?? rawLease['workflow_snapshot']),
-        runtimeTargetId: stringValue(data['runtime_target_id'] ?? rawLease['runtime_target_id']),
+        runtimeTargetId: runtimeContextTargetIdValue(data, rawLease),
         dataCapturePolicy: dataCapturePolicyValue(data['data_capture_policy'] ?? rawLease['data_capture_policy']),
     };
 }
-async function heartbeatHttp(profile, options) {
+async function heartbeatHttp(profile, options, dispatcher) {
     const capabilityPayload = managedExecutorCapabilities(profile.capabilities);
     if (isHostedManagedExecutorProfile(profile)) {
         await hostedManagedExecutorFetch(profile, 'POST', 'heartbeat', {
@@ -387,7 +862,9 @@ async function heartbeatHttp(profile, options) {
             access_mode: options.transport,
             runner_mode: options.lifecycle === 'ephemeral' ? 'viewport_managed' : 'self_hosted',
             runner_provider: options.lifecycle === 'ephemeral' ? 'viewport_cloud' : 'local',
-            context_execution_mode: options.lifecycle === 'ephemeral' ? 'viewport_managed' : 'customer_managed_context_worker',
+            context_execution_mode: options.lifecycle === 'ephemeral'
+                ? 'viewport_managed'
+                : 'customer_managed_context_worker',
             credential_mode: options.lifecycle === 'ephemeral' ? 'run_scoped_grant' : 'runner_local',
             runner_profile: stringValue(capabilityPayload['runner_pool']) ??
                 stringValue(capabilityPayload['runnerPool']) ??
@@ -399,7 +876,7 @@ async function heartbeatHttp(profile, options) {
                 },
             },
             capabilities: capabilityPayload,
-        });
+        }, undefined, undefined, [], dispatcher);
         return;
     }
     await workerRequest(profile, 'workers/heartbeat', {
@@ -412,7 +889,7 @@ async function heartbeatHttp(profile, options) {
         capabilities: profile.capabilities,
     });
 }
-async function syncLeaseHttp(profile, lease, execution) {
+async function syncLeaseHttp(profile, lease, execution, dispatcher) {
     const status = execution.status;
     if (isHostedManagedExecutorProfile(profile)) {
         if (!lease.runId) {
@@ -466,7 +943,7 @@ async function syncLeaseHttp(profile, lease, execution) {
                     message: `vpd worker marked run ${status}`,
                 },
             ],
-        }, lease.assignmentClaimToken, lease.leaseToken);
+        }, lease.assignmentClaimToken, lease.leaseToken, [], dispatcher);
         return;
     }
     await workerRequest(profile, `workers/leases/${encodeURIComponent(lease.id)}/sync`, {
@@ -496,7 +973,7 @@ async function executeHostedWorkflowClaim(profile, transport, lease) {
         if (existing) {
             if (existing.status === 'blocked') {
                 const body = await transport.pollRuntimeCommands(lease);
-                const runtimeSecretEnv = await materializeHostedRunCredentials(profile, lease);
+                const runtimeSecretEnv = await runtimeSecretEnvForHostedRun(profile, lease, transport);
                 const applied = await daemon.workflowRunner.applyRuntimeCommandBody(existing.id, body, {
                     runtimeSecretEnv,
                 });
@@ -524,15 +1001,16 @@ async function executeHostedWorkflowClaim(profile, transport, lease) {
         const directoryPath = path.resolve(lease.directoryPath ?? profile.workspaceRoot);
         await fs.mkdir(directoryPath, { recursive: true });
         const directory = await daemon.directoryManager.register(directoryPath);
-        const runtimeSecretEnv = await materializeHostedRunCredentials(profile, lease);
+        const runtimeSecretEnv = await runtimeSecretEnvForHostedRun(profile, lease, transport);
         const run = await daemon.workflowRunner.startRun({
             workflowYaml: lease.yamlSnapshot,
             workflowSourceRef: lease.sourceRef ?? `viewport://managed-executor/${lease.runId ?? lease.id}`,
             directoryId: directory.id,
-            inputs: lease.inputSnapshot,
+            inputs: hostedWorkflowInputs(profile, lease),
             resourceId: profile.workspaceId,
-            runtimeTargetId: lease.runtimeTargetId ?? profile.managedExecutorId,
+            runtimeTargetId: hostedRuntimeContextTargetId(profile, lease),
             platformRunId: lease.runId,
+            agentSessionId: lease.agentSessionId,
             resourceManifest: lease.resourceManifest,
             workflowAuthorityContract: lease.workflowAuthorityContract,
             dataCapturePolicy: lease.dataCapturePolicy,
@@ -562,7 +1040,7 @@ async function executeHostedWorkflowClaim(profile, transport, lease) {
         };
     }
 }
-async function materializeHostedRunCredentials(profile, lease) {
+async function materializeHostedRunCredentials(profile, lease, dispatcher) {
     if (!lease.runId) {
         throw new Error('Hosted managed executor credential materialization requires a workflow run id.');
     }
@@ -576,7 +1054,7 @@ async function materializeHostedRunCredentials(profile, lease) {
             credential: profile.credential,
             handle,
             ...repositoryForCredentialHandle(lease, handle),
-        }, lease.assignmentClaimToken, lease.leaseToken);
+        }, lease.assignmentClaimToken, lease.leaseToken, [], dispatcher);
         const parsed = (await response.json());
         const data = parsed['data'] && typeof parsed['data'] === 'object'
             ? parsed['data']
@@ -588,6 +1066,16 @@ async function materializeHostedRunCredentials(profile, lease) {
     }
     return runtimeSecretEnv;
 }
+async function runtimeSecretEnvForHostedRun(profile, lease, transport) {
+    const dispatcher = transport instanceof RelayWorkerTransport
+        ? (request) => transport.dispatchHostedManagedExecutorRequest(request)
+        : undefined;
+    return {
+        ...(await materializeHostedRunCredentials(profile, lease, dispatcher)),
+        ...gatewayLeaseCredentialEnv(lease.gateway),
+        ...gatewayLeaseEnv(lease.gateway),
+    };
+}
 function credentialHandlesFromLease(lease) {
     const workflow = yamlSnapshotDocument(lease);
     const handles = new Set();
@@ -743,7 +1231,7 @@ async function resumeBlockedHostedExecution(profile, transport, lease, execution
             }
             return execution;
         }
-        const runtimeSecretEnv = await materializeHostedRunCredentials(profile, lease);
+        const runtimeSecretEnv = await runtimeSecretEnvForHostedRun(profile, lease);
         const applied = await daemon.workflowRunner.applyRuntimeCommandBody(workflowRunId, body, {
             runtimeSecretEnv,
         });
@@ -772,11 +1260,252 @@ async function resumeBlockedHostedExecution(profile, transport, lease, execution
     }
     return execution;
 }
-async function fetchHostedAssignmentHttp(profile, lease) {
+async function maybeExecuteHostedSessionVerification(profile, transport, lease, execution) {
+    if (!isHostedManagedExecutorProfile(profile))
+        return;
+    if (execution.status !== 'completed' || !execution.run)
+        return;
+    const contract = await executableHostedSessionVerificationContract(transport, lease);
+    if (!contract || !verificationRunnerMayExecute(contract))
+        return;
+    const agentSessionId = verificationAgentSessionId(contract);
+    if (!agentSessionId)
+        return;
+    const commands = verificationCommands(contract);
+    if (commands.length === 0)
+        return;
+    const runDirectoryPath = execution.run.directoryPath ?? lease.directoryPath ?? profile.workspaceRoot;
+    const defaultCommandDirectory = verificationDefaultCommandDirectory(execution.run);
+    const commandResults = [];
+    const artifactRefs = [];
+    for (const command of commands) {
+        const name = verificationCommandName(command, commandResults.length + 1);
+        const commandText = verificationCommandText(command);
+        let result;
+        let executionError;
+        try {
+            const cwd = verificationCommandCwd(runDirectoryPath, command, defaultCommandDirectory);
+            result = await runShellCommand(commandText, '', cwd);
+        }
+        catch (error) {
+            executionError = errorMessage(error);
+            result = { exitCode: 1, stdout: '', stderr: '' };
+        }
+        const stdoutDigest = sha256Text(result.stdout);
+        const stderrDigest = sha256Text(result.stderr);
+        const status = result.exitCode === 0 ? 'passed' : 'failed';
+        artifactRefs.push(`verification:${name}:stdout:${stdoutDigest}`);
+        if (result.stderr.trim() !== '') {
+            artifactRefs.push(`verification:${name}:stderr:${stderrDigest}`);
+        }
+        commandResults.push({
+            schema: 'viewport.verification_command_result/v1',
+            name,
+            status,
+            required: command.required !== false,
+            exit_code: result.exitCode,
+            command_sha256: sha256Text(commandText),
+            stdout_sha256: stdoutDigest,
+            stderr_sha256: stderrDigest,
+            stdout_bytes: Buffer.byteLength(result.stdout, 'utf8'),
+            stderr_bytes: Buffer.byteLength(result.stderr, 'utf8'),
+            working_directory: verificationCommandWorkingDirectory(command) ??
+                verificationDisplayWorkingDirectory(runDirectoryPath, defaultCommandDirectory),
+            raw_output_included: false,
+            ...(executionError ? { error: executionError } : {}),
+        });
+    }
+    const requiredFailures = commandResults.filter((result) => result['required'] !== false && result['status'] !== 'passed');
+    const passedCount = commandResults.filter((result) => result['status'] === 'passed').length;
+    const status = requiredFailures.length > 0 ? 'failed' : 'passed';
+    const summary = status === 'passed'
+        ? `${passedCount}/${commandResults.length} verification commands passed.`
+        : `${requiredFailures.length} required verification command(s) failed.`;
+    await postHostedSessionVerificationAttempt(profile, transport, lease, contract, agentSessionId, {
+        status,
+        attempt_kind: 'verification',
+        summary,
+        artifact_refs: artifactRefs.slice(0, 50),
+        verification_pack: {
+            schema: 'viewport.verification_pack_result/v1',
+            source_schema: contract.schema ?? null,
+            agent_session_id: agentSessionId,
+            workflow_run_id: lease.runId,
+            policy_hash: typeof contract['policy_hash'] === 'string' ? contract['policy_hash'] : null,
+            command_results: commandResults,
+            required_artifacts: verificationRequiredArtifacts(contract),
+            raw_command_output_included: false,
+            agent_self_assessment_used: false,
+        },
+        repair_recommendation: status === 'passed'
+            ? { action: 'none' }
+            : {
+                action: 'ask_human',
+                failed_commands: requiredFailures.map((result) => result['name']),
+            },
+    });
+}
+async function executableHostedSessionVerificationContract(transport, lease) {
+    const contract = lease.sessionVerificationContract;
+    if (contract && verificationRunnerMayExecute(contract))
+        return contract;
+    if (!leaseMayHaveSessionVerification(lease))
+        return contract ?? null;
+    const refreshed = await transport.pollRuntimeCommands(lease);
+    return sessionVerificationContractFromBody(refreshed) ?? contract ?? null;
+}
+function leaseMayHaveSessionVerification(lease) {
+    const policyPin = recordValue(lease.workflowSnapshot?.['product20_policy_pin']);
+    return Boolean(lease.agentSessionId ||
+        stringValue(policyPin?.['agent_session_id']) ||
+        lease.sessionVerificationContract);
+}
+function sessionVerificationContractFromBody(body) {
+    const record = recordValue(body);
+    const data = recordValue(record?.['data']);
+    return (sessionVerificationContractValue(data?.['session_verification_contract'] ??
+        data?.['sessionVerificationContract'] ??
+        record?.['session_verification_contract'] ??
+        record?.['sessionVerificationContract']) ?? null);
+}
+function sessionVerificationContractValue(value) {
+    const record = recordValue(value);
+    if (!record)
+        return undefined;
+    return record;
+}
+function verificationRunnerMayExecute(contract) {
+    const access = contract.access_model ?? contract.accessModel ?? {};
+    return access.runner_may_execute_commands === true || access.runnerMayExecuteCommands === true;
+}
+function verificationAgentSessionId(contract) {
+    return contract.agent_session_id ?? contract.agentSessionId ?? null;
+}
+function verificationCommands(contract) {
+    return (contract.commands ?? []).filter((command) => verificationCommandText(command) !== '');
+}
+function verificationCommandName(command, index) {
+    return command.name?.trim() || `verification-${index}`;
+}
+function verificationCommandText(command) {
+    return command.command?.trim() ?? '';
+}
+function verificationCommandWorkingDirectory(command) {
+    return command.working_directory?.trim() || command.workingDirectory?.trim() || null;
+}
+function verificationCommandCwd(runDirectoryPath, command, defaultDirectoryPath) {
+    const workingDirectory = verificationCommandWorkingDirectory(command);
+    const root = path.resolve(runDirectoryPath);
+    const resolved = workingDirectory
+        ? path.resolve(root, workingDirectory)
+        : path.resolve(defaultDirectoryPath ?? root);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('Verification command working_directory must stay inside the run directory.');
+    }
+    return resolved;
+}
+function verificationDefaultCommandDirectory(run) {
+    const root = path.resolve(run.directoryPath);
+    for (const node of Object.values(run.nodes ?? {})) {
+        if (node.type !== 'checkout')
+            continue;
+        const candidate = typeof node.outputs?.['path'] === 'string' ? node.outputs['path'] : null;
+        if (!candidate)
+            continue;
+        const resolved = path.resolve(candidate);
+        const relative = path.relative(root, resolved);
+        if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+            return resolved;
+        }
+    }
+    return root;
+}
+function verificationDisplayWorkingDirectory(runDirectoryPath, directoryPath) {
+    const root = path.resolve(runDirectoryPath);
+    const resolved = path.resolve(directoryPath);
+    const relative = path.relative(root, resolved);
+    if (relative === '')
+        return '.';
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        return '.';
+    return relative;
+}
+function verificationRequiredArtifacts(contract) {
+    return contract.required_artifacts ?? contract.requiredArtifacts ?? [];
+}
+async function runShellCommand(command, stdin, cwd = process.cwd()) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('sh', ['-lc', command], {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: process.env,
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => {
+            stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+            });
+        });
+        child.stdin.end(stdin);
+    });
+}
+function sha256Text(value) {
+    return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function postHostedSessionVerificationAttempt(profile, transport, lease, contract, agentSessionId, payload) {
+    if (!lease.runId) {
+        throw new Error('Hosted session verification requires a workflow run id.');
+    }
+    const runLeaseToken = lease.assignmentClaimToken ?? lease.leaseToken;
+    if (!runLeaseToken) {
+        throw new Error('Hosted session verification requires a run lease token.');
+    }
+    const suffix = hostedVerificationRuntimePathSuffix(profile, contract, agentSessionId) ??
+        `workflow-runs/${encodeURIComponent(lease.runId)}/agent-sessions/${encodeURIComponent(agentSessionId)}/verification-attempts`;
+    const dispatcher = transport instanceof RelayWorkerTransport
+        ? (request) => transport.dispatchHostedManagedExecutorRequest(request)
+        : undefined;
+    await hostedManagedExecutorFetch(profile, 'POST', suffix, {
+        credential: profile.credential,
+        ...payload,
+    }, undefined, runLeaseToken, [], dispatcher);
+}
+function hostedVerificationRuntimePathSuffix(profile, contract, agentSessionId) {
+    const runtimeTool = contract.runtime_tool ?? contract.runtimeTool ?? {};
+    const endpoint = runtimeTool.runtime_endpoint ?? runtimeTool.runtimeEndpoint;
+    if (typeof endpoint !== 'string' || endpoint.trim() === '')
+        return null;
+    const normalized = endpoint.trim();
+    const prefix = `/api/runtime/workspaces/${encodeURIComponent(profile.workspaceId ?? '')}/managed-executors/${encodeURIComponent(profile.managedExecutorId ?? '')}/`;
+    if (normalized.startsWith(prefix)) {
+        return normalized.slice(prefix.length);
+    }
+    const fallback = `/workflow-runs/`;
+    const index = normalized.indexOf(fallback);
+    if (index >= 0 && normalized.includes(`/agent-sessions/${encodeURIComponent(agentSessionId)}/`)) {
+        return normalized.slice(index + 1);
+    }
+    return null;
+}
+async function fetchHostedAssignmentHttp(profile, lease, dispatcher) {
     if (!lease.runId) {
         throw new Error('Hosted managed executor assignment polling requires a workflow run id.');
     }
-    const response = await hostedManagedExecutorFetch(profile, 'GET', `workflow-runs/${encodeURIComponent(lease.runId)}`, {}, lease.assignmentClaimToken, lease.leaseToken, [429]);
+    const response = await hostedManagedExecutorFetch(profile, 'GET', `workflow-runs/${encodeURIComponent(lease.runId)}`, {}, lease.assignmentClaimToken, lease.leaseToken, [429], dispatcher);
     if (response.status === 429) {
         await sleep(retryAfterMs(response));
         return { runtime_commands: [], _viewport_worker_retry: true };
@@ -884,22 +1613,26 @@ function isHostedManagedExecutorProfile(profile) {
     return Boolean(profile.workspaceId && profile.managedExecutorId && profile.credential);
 }
 function managedExecutorCapabilities(capabilities) {
+    const { schema: _schema, ...normalized } = capabilities;
     const agents = capabilities['agents'];
     if (!Array.isArray(agents))
-        return capabilities;
+        return normalized;
+    const objectAgents = agents
+        .filter((agent) => typeof agent === 'object' && agent !== null && !Array.isArray(agent))
+        .map((agent) => {
+        const record = agent;
+        const id = stringValue(record['id']);
+        return id ? [id, record] : null;
+    })
+        .filter((entry) => entry !== null);
+    if (objectAgents.length === 0)
+        return normalized;
     return {
-        ...capabilities,
-        agents: Object.fromEntries(agents
-            .filter((agent) => typeof agent === 'object' && agent !== null && !Array.isArray(agent))
-            .map((agent) => {
-            const record = agent;
-            const id = stringValue(record['id']);
-            return id ? [id, record] : null;
-        })
-            .filter((entry) => entry !== null)),
+        ...normalized,
+        agents: Object.fromEntries(objectAgents),
     };
 }
-async function hostedManagedExecutorFetch(profile, method, path, body, assignmentClaimToken, runLeaseToken, allowedStatuses = []) {
+async function hostedManagedExecutorFetch(profile, method, path, body, assignmentClaimToken, runLeaseToken, allowedStatuses = [], dispatcher) {
     if (!profile.workspaceId || !profile.managedExecutorId || !profile.credential) {
         throw new Error('Hosted managed executor profile is missing workspace, executor, or credential.');
     }
@@ -910,26 +1643,37 @@ async function hostedManagedExecutorFetch(profile, method, path, body, assignmen
     const maxAttempts = hostedManagedExecutorMaxAttempts();
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         const signed = await signWorkerRequest(profile, method, requestPath, serialized);
-        const response = await transportFetch(url, {
+        const headers = {
+            Authorization: `Bearer ${profile.credential}`,
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            ...(runLeaseToken
+                ? { 'X-Viewport-Run-Lease': runLeaseToken }
+                : assignmentClaimToken
+                    ? { 'X-Viewport-Assignment-Claim': assignmentClaimToken }
+                    : {}),
+            'X-Viewport-Worker-Fingerprint': profile.publicKeyFingerprint,
+            'X-Viewport-Worker-Timestamp': signed.timestamp,
+            'X-Viewport-Worker-Nonce': signed.nonce,
+            'X-Viewport-Worker-Body-SHA256': signed.bodySha256,
+            'X-Viewport-Worker-Signature': signed.signature,
+            ...(signed.serverId ? { 'X-Viewport-Server-Id': signed.serverId } : {}),
+        };
+        const request = {
             method,
-            headers: {
-                Authorization: `Bearer ${profile.credential}`,
-                Accept: 'application/json',
-                'Content-Type': 'application/json',
-                ...(runLeaseToken
-                    ? { 'X-Viewport-Run-Lease': runLeaseToken }
-                    : assignmentClaimToken
-                        ? { 'X-Viewport-Assignment-Claim': assignmentClaimToken }
-                        : {}),
-                'X-Viewport-Worker-Fingerprint': profile.publicKeyFingerprint,
-                'X-Viewport-Worker-Timestamp': signed.timestamp,
-                'X-Viewport-Worker-Nonce': signed.nonce,
-                'X-Viewport-Worker-Body-SHA256': signed.bodySha256,
-                'X-Viewport-Worker-Signature': signed.signature,
-                ...(signed.serverId ? { 'X-Viewport-Server-Id': signed.serverId } : {}),
-            },
-            ...(method === 'GET' ? {} : { body: serialized }),
-        });
+            path,
+            requestPath,
+            url,
+            serialized,
+            headers,
+        };
+        const response = dispatcher
+            ? await dispatcher(request)
+            : await transportFetch(url, {
+                method,
+                headers,
+                ...(method === 'GET' ? {} : { body: serialized }),
+            });
         if (response.ok || allowedStatuses.includes(response.status)) {
             return response;
         }
@@ -970,6 +1714,27 @@ function retryAfterMs(response) {
     }
     return 5_000;
 }
+function relayWorkerConnectionTimeoutMs() {
+    return positiveIntegerFromEnv('VIEWPORT_RELAY_WORKER_CONNECT_TIMEOUT_MS') ?? 10_000;
+}
+function relayWorkerRequestTimeoutMs() {
+    return positiveIntegerFromEnv('VIEWPORT_RELAY_WORKER_REQUEST_TIMEOUT_MS') ?? 60_000;
+}
+function positiveIntegerFromEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function relayWsBaseUrlFromServerUrl(serverUrl) {
+    const parsed = new URL(serverUrl);
+    const protocol = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+    const hostname = parsed.hostname.startsWith('api.')
+        ? `relay.${parsed.hostname.slice(4)}`
+        : parsed.hostname;
+    return `${protocol}//${hostname}${parsed.port ? `:${parsed.port}` : ''}/ws`;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1002,6 +1767,11 @@ function recordValue(value) {
         return undefined;
     return value;
 }
+function arrayOfStrings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string' && item.trim() !== '')
+        : [];
+}
 function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }