@the-open-engine/zeroshot 6.29.0 → 6.30.0

package/lib/cluster-worker/engine-adapter.js

@@ -2,6 +2,11 @@
 
 const { cloneJson } = require('./object-utils');
 const { inputFromRequest } = require('./engine-input');
+const {
+  createAdapterFacade,
+  declaredFailureEvent,
+  frozenResourceStatus,
+} = require('./engine-adapter-common');
 
 const TERMINAL_TOPICS = new Set(['CLUSTER_COMPLETE', 'CLUSTER_FAILED']);
 
@@ -9,21 +14,20 @@ function messageKey(message) {
   return message.id ?? `${message.timestamp}:${message.topic}:${message.sender}`;
 }
 
+function completionPayload(data) {
+  const payload = {};
+  if (Object.prototype.hasOwnProperty.call(data, 'result')) payload.result = data.result;
+  if (Object.prototype.hasOwnProperty.call(data, 'artifacts')) payload.artifacts = data.artifacts;
+  return payload;
+}
+
 function terminalEventFromMessage(message) {
   const data = message.content?.data || {};
   if (message.topic === 'CLUSTER_COMPLETE') {
-    let prSummary = null;
-    if (typeof data.pr_url === 'string' && data.pr_url) {
-      const number = Number.isSafeInteger(data.pr_number) ? ` #${data.pr_number}` : '';
-      prSummary = `Pull request${number} created: ${data.pr_url}`;
-    }
     return {
       type: 'complete',
-      summary: prSummary || data.reason || message.content?.text,
-      ...(Object.prototype.hasOwnProperty.call(data, 'result') ? { result: data.result } : {}),
-      ...(Object.prototype.hasOwnProperty.call(data, 'artifacts')
-        ? { artifacts: data.artifacts }
-        : {}),
+      summary: data.reason || message.content?.text,
+      ...completionPayload(data),
     };
   }
   return {
@@ -133,7 +137,7 @@ class CurrentEngineAdapter {
       try {
         this.foldDurableMessages();
       } catch {
-        this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+        this.resource.onEvent(declaredFailureEvent());
       }
     });
   }
@@ -198,12 +202,12 @@ class CurrentEngineAdapter {
   foldClusterState(cluster) {
     if (!cluster) {
       if (!this.terminalObserved) {
-        this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+        this.resource.onEvent(declaredFailureEvent());
       }
       return 'released';
     }
     if (!this.terminalObserved && ['failed', 'stopped', 'killed'].includes(cluster.state)) {
-      this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+      this.resource.onEvent(declaredFailureEvent());
     } else if (cluster.state === 'running') {
       this.resource.onEvent({ type: 'running' });
     }
@@ -215,13 +219,11 @@ class CurrentEngineAdapter {
     this.foldDurableMessages();
     const cluster = this.orchestrator.getCluster(this.resource.clusterId);
     if (!cluster && !this.startSettled) {
-      return Object.freeze({ clusterId: this.resource.clusterId, state: 'starting' });
+      return frozenResourceStatus(this.resource, 'starting');
     }
     const state = this.foldClusterState(cluster);
-    if (!cluster) return Object.freeze({ clusterId: this.resource.clusterId, state });
-    return Object.freeze({
-      clusterId: this.resource.clusterId,
-      state,
+    if (!cluster) return frozenResourceStatus(this.resource, state);
+    return frozenResourceStatus(this.resource, state, {
       messageCount: cluster.ledger.count({ cluster_id: this.resource.clusterId }),
       pidAliveDiagnostic: this.orchestrator.getStatus(this.resource.clusterId).isZombie !== true,
     });
@@ -233,16 +235,16 @@ class CurrentEngineAdapter {
     this.stopPromise ||= this.stopResource();
     return this.stopPromise;
   }
-
   async waitForAllocatedCluster() {
     let cluster = this.orchestrator.getCluster(this.resource.clusterId);
     while (!cluster && !this.startSettled && !this.closed) {
-      await new Promise((resolve) => setTimeout(resolve, 10));
+      await new Promise((resolve) => {
+        setTimeout(resolve, 10);
+      });
       cluster = this.orchestrator.getCluster(this.resource.clusterId);
     }
     return cluster;
   }
-
   stopAllocatedCluster(cluster = this.orchestrator.getCluster(this.resource.clusterId)) {
     if (!cluster) return Promise.resolve(false);
     if (cluster.state === 'stopped' || cluster.state === 'killed') return Promise.resolve(true);
@@ -251,7 +253,6 @@ class CurrentEngineAdapter {
       .then(() => true);
     return this.allocatedStopPromise;
   }
-
   async stopResource() {
     this.cleanupPromise ||= this.waitForAllocatedCluster()
       .then((cluster) => this.stopAllocatedCluster(cluster))
@@ -283,14 +284,7 @@ class CurrentEngineAdapter {
 }
 
 function createCurrentEngineAdapter(options = {}) {
-  const adapter = new CurrentEngineAdapter(options);
-  return Object.freeze({
-    start: adapter.start.bind(adapter),
-    status: adapter.status.bind(adapter),
-    stop: adapter.stop.bind(adapter),
-    waitForCleanup: adapter.waitForCleanup.bind(adapter),
-    close: adapter.close.bind(adapter),
-  });
+  return createAdapterFacade(new CurrentEngineAdapter(options));
 }
 
 module.exports = { createCurrentEngineAdapter, inputFromRequest, terminalEventFromMessage };

package/lib/cluster-worker/engine-start.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { CANCELLED, createArtifactPreparation } = require('./runtime-support');
+
+function createEngineStart(runtime, request, clusterId) {
+  const prepareArtifacts =
+    request.source === 'artifact'
+      ? createArtifactPreparation({
+          resolver: runtime.artifactResolver,
+          artifacts: request.artifacts,
+          clusterId,
+          getProfile: () => runtime.profile,
+          signal: runtime.preparationController.signal,
+          reportFailure: runtime.cleanupFailureReporter,
+        })
+      : null;
+  return Promise.resolve(
+    runtime.engineAdapter.start({
+      request,
+      profile: runtime.profile,
+      ...(prepareArtifacts ? { prepareArtifacts } : {}),
+      clusterId,
+      onEvent: runtime.onEngineEvent,
+    })
+  );
+}
+
+function assertEngineResource(resource, request, clusterId) {
+  if (resource?.clusterId && resource.clusterId !== clusterId) {
+    throw new Error('Engine allocated a cluster with a different id');
+  }
+  if (request.source === 'artifact' && resource?.artifactsStaged !== true) {
+    throw new Error('Engine started without staging artifact input');
+  }
+}
+
+async function acceptEngineStart(runtime, resource, request, clusterId) {
+  if (resource === CANCELLED) {
+    if (!runtime.machine.terminalReceipt) await runtime.machine.result();
+    return runtime.machine.status();
+  }
+  assertEngineResource(resource, request, clusterId);
+  if (runtime.machine.state === 'starting') runtime.machine.transition('running');
+  return runtime.machine.status();
+}
+
+async function handleEngineStartFailure(runtime, error) {
+  if (runtime.claimTerminalAuthority('engine:start')) {
+    runtime.machine.terminal(runtime.failureReceipt('failed', 'crash', 'declared_failure'));
+  }
+  await runtime.stopEngine();
+  if (runtime.terminalAuthority !== 'engine:start' && !runtime.machine.terminalReceipt) {
+    await runtime.machine.result();
+    return runtime.machine.status();
+  }
+  throw error;
+}
+
+module.exports = { acceptEngineStart, createEngineStart, handleEngineStartFailure };

package/lib/cluster-worker/index.js

@@ -1,17 +1,20 @@
 'use strict';
 
 const { validateLegacyShipRequest } = require('./contracts');
-const { createCurrentEngineAdapter } = require('./engine-adapter');
 const { cloneJson, deepFreeze } = require('./object-utils');
 const { createDeploymentProfileRegistry, DEFAULT_BOUNDS } = require('./profiles');
 const {
   CANCELLED,
   assertIsolatedProfile,
-  createArtifactPreparation,
   errorOutcome,
   resolveRuntimeDependencies,
   runCancellable,
 } = require('./runtime-support');
+const {
+  acceptEngineStart,
+  createEngineStart,
+  handleEngineStartFailure,
+} = require('./engine-start');
 const { releaseEngine, stopEngine } = require('./runtime-engine');
 const { LegacyWorkerStateMachine } = require('./state-machine');
 const { createTerminalNormalizer } = require('./terminal-normalizer');
@@ -131,49 +134,14 @@ class LegacyClusterWorkerRuntime {
   async startEngine(request, clusterId) {
     this.engineStartAttempted = true;
     try {
-      const prepareArtifacts =
-        request.source === 'artifact'
-          ? createArtifactPreparation({
-              resolver: this.artifactResolver,
-              artifacts: request.artifacts,
-              clusterId,
-              getProfile: () => this.profile,
-              signal: this.preparationController.signal,
-              reportFailure: this.cleanupFailureReporter,
-            })
-          : null;
-      const engineStart = Promise.resolve(
-        this.engineAdapter.start({
-          request,
-          profile: this.profile,
-          ...(prepareArtifacts ? { prepareArtifacts } : {}),
-          clusterId,
-          onEvent: this.onEngineEvent,
-        })
-      );
-      const resource = await Promise.race([engineStart, this.terminalClaimed]);
-      if (resource === CANCELLED) {
-        if (!this.machine.terminalReceipt) await this.machine.result();
-        return this.machine.status();
-      }
-      if (resource?.clusterId && resource.clusterId !== clusterId) {
-        throw new Error('Engine allocated a cluster with a different id');
-      }
-      if (request.source === 'artifact' && resource?.artifactsStaged !== true) {
-        throw new Error('Engine started without staging artifact input');
-      }
-      if (this.machine.state === 'starting') this.machine.transition('running');
-      return this.machine.status();
+      const resource = await Promise.race([
+        createEngineStart(this, request, clusterId),
+        this.terminalClaimed,
+      ]);
+      const status = await acceptEngineStart(this, resource, request, clusterId);
+      return status;
     } catch (error) {
-      if (this.claimTerminalAuthority('engine:start')) {
-        this.machine.terminal(this.failureReceipt('failed', 'crash', 'declared_failure'));
-      }
-      await this.stopEngine();
-      if (this.terminalAuthority !== 'engine:start' && !this.machine.terminalReceipt) {
-        await this.machine.result();
-        return this.machine.status();
-      }
-      throw error;
+      return handleEngineStartFailure(this, error);
     }
   }
   beginLifecycle() {
@@ -187,7 +155,7 @@ class LegacyClusterWorkerRuntime {
     this.armExecutionTimeout(this.initialExecutionBound());
     return clusterId;
   }
-  async start(request) {
+  claimStartRequest(request) {
     if (this.startClaimed) throw new Error('Worker facade permits exactly one start');
     const requestSnapshot = deepFreeze(cloneJson(request));
     validateLegacyShipRequest(requestSnapshot);
@@ -196,33 +164,43 @@ class LegacyClusterWorkerRuntime {
     }
     // Claim synchronously so concurrent calls cannot allocate two resources.
     this.startClaimed = true;
-    let clusterId;
+    return requestSnapshot;
+  }
+  resolveStartProfile(request) {
+    const profileResolution = this.profileRegistry.resolve(
+      request.isolationProfile,
+      request.providerProfile,
+      Object.freeze({ signal: this.preparationController.signal })
+    );
+    if (!profileResolution || typeof profileResolution.then !== 'function') {
+      this.profile = assertIsolatedProfile(profileResolution, request);
+    }
+    return profileResolution;
+  }
+  async handleStartFailure(error) {
+    if (this.terminalAuthority !== null) {
+      if (!this.machine.terminalReceipt) await this.machine.result();
+      return this.machine.status();
+    }
+    if (!this.machine.clusterId) {
+      this.startClaimed = false;
+      throw error;
+    }
+    if (this.claimTerminalAuthority('engine:start-setup')) {
+      this.machine.terminal(this.failureReceipt('failed', 'crash', 'declared_failure'));
+    }
+    throw error;
+  }
+  async start(request) {
+    const requestSnapshot = this.claimStartRequest(request);
     try {
-      const profileResolution = this.profileRegistry.resolve(
-        requestSnapshot.isolationProfile,
-        requestSnapshot.providerProfile,
-        Object.freeze({ signal: this.preparationController.signal })
-      );
-      if (!profileResolution || typeof profileResolution.then !== 'function') {
-        this.profile = assertIsolatedProfile(profileResolution, requestSnapshot);
-      }
-      clusterId = this.beginLifecycle();
+      const profileResolution = this.resolveStartProfile(requestSnapshot);
+      const clusterId = this.beginLifecycle();
       const prepared = await this.prepareStart(requestSnapshot, clusterId, profileResolution);
       if (prepared === CANCELLED) return this.machine.status();
       return this.startEngine(requestSnapshot, clusterId);
     } catch (error) {
-      if (this.terminalAuthority !== null) {
-        if (!this.machine.terminalReceipt) await this.machine.result();
-        return this.machine.status();
-      }
-      if (!this.machine.clusterId) {
-        this.startClaimed = false;
-        throw error;
-      }
-      if (this.machine.clusterId && this.claimTerminalAuthority('engine:start-setup')) {
-        this.machine.terminal(this.failureReceipt('failed', 'crash', 'declared_failure'));
-      }
-      throw error;
+      return this.handleStartFailure(error);
     }
   }
   status() {
@@ -283,6 +261,10 @@ class LegacyClusterWorkerRuntime {
   }
 }
 
+function createCurrentEngineAdapter(...args) {
+  return require('./engine-adapter').createCurrentEngineAdapter(...args);
+}
+
 function createLegacyClusterWorker(dependencies = {}) {
   return createWorkerFacade(new LegacyClusterWorkerRuntime(dependencies));
 }

package/lib/cluster-worker/profiles.js

@@ -24,44 +24,6 @@ const DEFAULT_PROVIDER_PROFILES = Object.freeze({
   }),
 });
 
-const HOSTED_CODEX_OPENROUTER_PROFILE = 'provider.codex-openrouter@1';
-const HOSTED_CODEX_OPENROUTER_PR_PROFILE = 'provider.codex-openrouter-pr@1';
-const DEFAULT_HOSTED_MODEL = 'openai/gpt-5.4';
-
-function providerProfilesFromEnvironment(environment = process.env) {
-  if (environment.ZEROSHOT_HOSTED_CODEX_OPENROUTER !== '1') {
-    return DEFAULT_PROVIDER_PROFILES;
-  }
-  const model = environment.ZEROSHOT_HOSTED_MODEL || DEFAULT_HOSTED_MODEL;
-  const levelOverrides = Object.freeze({
-    level1: Object.freeze({ model, reasoningEffort: 'medium' }),
-    level2: Object.freeze({ model, reasoningEffort: 'high' }),
-    level3: Object.freeze({ model, reasoningEffort: 'xhigh' }),
-  });
-  const hostedSettings = {
-    templateParams: { task_type: 'TASK' },
-    providerSettings: {
-      codex: {
-        defaultLevel: 'level2',
-        levelOverrides,
-      },
-    },
-  };
-  return deepFreeze({
-    ...DEFAULT_PROVIDER_PROFILES,
-    [HOSTED_CODEX_OPENROUTER_PROFILE]: {
-      configName: 'base-templates/single-worker',
-      providerOverride: 'codex',
-      settings: hostedSettings,
-    },
-    [HOSTED_CODEX_OPENROUTER_PR_PROFILE]: {
-      configName: 'base-templates/worker-validator',
-      providerOverride: 'codex',
-      settings: hostedSettings,
-    },
-  });
-}
-
 function own(map, key) {
   return Object.prototype.hasOwnProperty.call(map, key) ? map[key] : null;
 }
@@ -76,7 +38,7 @@ function validateBounds(bounds) {
 
 function createDeploymentProfileRegistry(options = {}) {
   const isolationProfiles = options.isolationProfiles || DEFAULT_ISOLATION_PROFILES;
-  const providerProfiles = options.providerProfiles || providerProfilesFromEnvironment();
+  const providerProfiles = options.providerProfiles || DEFAULT_PROVIDER_PROFILES;
   const defaultBounds = { ...DEFAULT_BOUNDS, ...(options.bounds || {}) };
   validateBounds(defaultBounds);
   const bounds = deepFreeze(defaultBounds);
@@ -115,8 +77,5 @@ module.exports = {
   DEFAULT_BOUNDS,
   DEFAULT_ISOLATION_PROFILES,
   DEFAULT_PROVIDER_PROFILES,
-  HOSTED_CODEX_OPENROUTER_PROFILE,
-  HOSTED_CODEX_OPENROUTER_PR_PROFILE,
   createDeploymentProfileRegistry,
-  providerProfilesFromEnvironment,
 };

package/lib/cluster-worker/runtime-dependencies.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { randomUUID } = require('crypto');
+const { createDeploymentProfileRegistry } = require('./profiles');
+
+const DEPENDENCY_KEYS = new Set([
+  'profileRegistry',
+  'artifactResolver',
+  'artifactReceiptSink',
+  'engineAdapter',
+  'clock',
+  'timers',
+  'idFactory',
+  'cleanupFailureReporter',
+]);
+
+function assertRuntimeDependencies(dependencies) {
+  const unknownDependencies = Object.keys(dependencies).filter((key) => !DEPENDENCY_KEYS.has(key));
+  if (unknownDependencies.length > 0) {
+    throw new Error(`Unsupported worker dependencies: ${unknownDependencies.join(', ')}`);
+  }
+  if (
+    dependencies.cleanupFailureReporter !== undefined &&
+    typeof dependencies.cleanupFailureReporter !== 'function'
+  ) {
+    throw new Error('cleanupFailureReporter must be a function');
+  }
+}
+
+function applyRuntimeDependencyDefaults(dependencies, defaultCleanupFailureReporter) {
+  return {
+    profileRegistry: dependencies.profileRegistry || createDeploymentProfileRegistry(),
+    artifactResolver: dependencies.artifactResolver || null,
+    artifactReceiptSink: dependencies.artifactReceiptSink || null,
+    engineAdapter:
+      dependencies.engineAdapter || require('./engine-adapter').createCurrentEngineAdapter(),
+    clock: dependencies.clock || (() => Date.now()),
+    timers: dependencies.timers || { setTimeout, clearTimeout },
+    idFactory: dependencies.idFactory || (() => `legacy-worker-${randomUUID()}`),
+    cleanupFailureReporter: dependencies.cleanupFailureReporter || defaultCleanupFailureReporter,
+  };
+}
+
+function resolveRuntimeDependencies(dependencies, defaultCleanupFailureReporter) {
+  assertRuntimeDependencies(dependencies);
+  return applyRuntimeDependencyDefaults(dependencies, defaultCleanupFailureReporter);
+}
+
+module.exports = { resolveRuntimeDependencies };

package/lib/cluster-worker/runtime-support.js

@@ -1,25 +1,12 @@
 'use strict';
 
-const { randomUUID } = require('crypto');
 const { validateArtifactRef, validateWorkerOutcome } = require('./contracts');
-const { createCurrentEngineAdapter } = require('./engine-adapter');
 const { cloneJson, deepFreeze } = require('./object-utils');
-const { createDeploymentProfileRegistry } = require('./profiles');
 const { resolveRunPlan } = require('../run-plan');
+const { resolveRuntimeDependencies: resolveDependencies } = require('./runtime-dependencies');
 
 const CANCELLED = Symbol('cancelled');
 
-const DEPENDENCY_KEYS = new Set([
-  'profileRegistry',
-  'artifactResolver',
-  'artifactReceiptSink',
-  'engineAdapter',
-  'clock',
-  'timers',
-  'idFactory',
-  'cleanupFailureReporter',
-]);
-
 async function stageArtifacts(resolver, artifacts, context) {
   if (artifacts.length === 0) return deepFreeze({ artifacts: [] });
   if (context.signal?.aborted) return CANCELLED;
@@ -200,26 +187,7 @@ async function stopEngineWithinBound({ engineAdapter, timers, shutdownMs }) {
 }
 
 function resolveRuntimeDependencies(dependencies) {
-  const unknownDependencies = Object.keys(dependencies).filter((key) => !DEPENDENCY_KEYS.has(key));
-  if (unknownDependencies.length > 0) {
-    throw new Error(`Unsupported worker dependencies: ${unknownDependencies.join(', ')}`);
-  }
-  if (
-    dependencies.cleanupFailureReporter !== undefined &&
-    typeof dependencies.cleanupFailureReporter !== 'function'
-  ) {
-    throw new Error('cleanupFailureReporter must be a function');
-  }
-  return {
-    profileRegistry: dependencies.profileRegistry || createDeploymentProfileRegistry(),
-    artifactResolver: dependencies.artifactResolver || null,
-    artifactReceiptSink: dependencies.artifactReceiptSink || null,
-    engineAdapter: dependencies.engineAdapter || createCurrentEngineAdapter(),
-    clock: dependencies.clock || (() => Date.now()),
-    timers: dependencies.timers || { setTimeout, clearTimeout },
-    idFactory: dependencies.idFactory || (() => `legacy-worker-${randomUUID()}`),
-    cleanupFailureReporter: dependencies.cleanupFailureReporter || defaultCleanupFailureReporter,
-  };
+  return resolveDependencies(dependencies, defaultCleanupFailureReporter);
 }
 
 function assertProfilePlan(profile) {

package/lib/cluster-worker/terminal-normalizer.js

@@ -5,17 +5,16 @@ const { cloneJson, deepFreeze } = require('./object-utils');
 const { collectReceipts } = require('./runtime-support');
 
 async function resultFromEvent(event, options) {
-  let summary;
-  let status = 'succeeded';
-  let declaredArtifacts = event.artifacts;
+  let result;
+  let declaredArtifacts;
   if (Object.prototype.hasOwnProperty.call(event, 'result')) {
     validateLegacyShipResult(event.result);
-    summary = event.result.summary;
-    status = event.result.status;
+    result = event.result;
     declaredArtifacts = event.result.artifacts;
   } else {
-    summary = event.summary;
-    validateLegacyShipResult({ summary, status, artifacts: [] });
+    result = { summary: event.summary, status: 'succeeded', artifacts: [] };
+    validateLegacyShipResult(result);
+    declaredArtifacts = [];
   }
   const artifacts = await collectReceipts(options.artifactReceiptSink, declaredArtifacts, {
     clusterId: options.machine.clusterId,
@@ -24,9 +23,9 @@ async function resultFromEvent(event, options) {
     reportCleanupFailure: options.cleanupFailureReporter,
   });
   if (artifacts === options.cancelled) return options.cancelled;
-  const result = { summary, status, artifacts };
-  validateLegacyShipResult(result);
-  return result;
+  const normalized = { ...result, artifacts };
+  validateLegacyShipResult(normalized);
+  return normalized;
 }
 
 function createTerminalNormalizer(options) {

package/lib/hosted-session/authority.cjs

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizedAuthority = normalizedAuthority;
+exports.validateHostedAccess = validateHostedAccess;
+const index_js_1 = require("../cluster/index.cjs");
+const LOOPBACK_HOSTS = Object.freeze({
+    '127.0.0.1': true,
+    '::1': true,
+    '[::1]': true,
+});
+function parseCanonicalUrl(value, message, code) {
+    try {
+        if (/[\u0000-\u0020\u007f]/.test(value))
+            throw new TypeError('unsafe URL code point');
+        const url = new URL(value);
+        if (url.href !== value && url.origin !== value)
+            throw new TypeError('non-canonical URL');
+        return url;
+    }
+    catch {
+        throw new index_js_1.ClusterConfigError(message, code);
+    }
+}
+function hasOriginSuffix(url) {
+    return Boolean(url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash);
+}
+function normalizedAuthority(value) {
+    const message = 'targetAuthority must be an HTTPS or literal-loopback HTTP origin';
+    const url = parseCanonicalUrl(value, message, 'INVALID_TARGET_AUTHORITY');
+    const loopbackHttp = url.protocol === 'http:' && LOOPBACK_HOSTS[url.hostname] === true;
+    if ((url.protocol !== 'https:' && !loopbackHttp) || hasOriginSuffix(url) ||
+        value !== url.origin) {
+        throw new index_js_1.ClusterConfigError(message, 'INVALID_TARGET_AUTHORITY');
+    }
+    return url.origin;
+}
+function accessAuthorityMatches(endpoint, target) {
+    const expectedProtocol = target.protocol === 'http:' ? 'ws:' : 'wss:';
+    return (endpoint.protocol === expectedProtocol &&
+        endpoint.host === target.host &&
+        !endpoint.username &&
+        !endpoint.password &&
+        !endpoint.search &&
+        !endpoint.hash);
+}
+function validateHostedAccess(access, targetAuthority) {
+    const endpoint = parseCanonicalUrl(access.websocketUrl, 'access endpoint must be an absolute target WebSocket URL', 'INVALID_ACCESS_ENDPOINT');
+    if (endpoint.href !== access.websocketUrl ||
+        !accessAuthorityMatches(endpoint, new URL(targetAuthority))) {
+        throw new index_js_1.ClusterConfigError('access endpoint must remain on the exact target authority', 'INVALID_ACCESS_ENDPOINT');
+    }
+    if (access.protocol !== 'openengine.cluster/v1' ||
+        access.tokenType !== 'Bearer' ||
+        access.accessToken.length === 0) {
+        throw new index_js_1.ClusterConfigError('access grant does not match the hosted session contract', 'INVALID_ACCESS_GRANT');
+    }
+}

package/lib/hosted-session/authority.d.cts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;

package/lib/hosted-session/authority.d.mts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;

package/lib/hosted-session/authority.d.ts

@@ -0,0 +1,3 @@
+import type { HostedAccess } from './types.js';
+export declare function normalizedAuthority(value: string): string;
+export declare function validateHostedAccess(access: HostedAccess, targetAuthority: string): void;