@the-open-engine/zeroshot 6.6.0 → 6.7.0

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

@@ -0,0 +1,50 @@
+'use strict';
+
+const { DEFAULT_BOUNDS } = require('./profiles');
+const { reportLateFailure, stopEngineWithinBound } = require('./runtime-support');
+
+function stopEngine(runtime) {
+  runtime.engineStopPromise ||= stopEngineWithinBound({
+    engineAdapter: runtime.engineAdapter,
+    timers: runtime.timers,
+    shutdownMs: runtime.profile?.bounds.shutdownMs || DEFAULT_BOUNDS.shutdownMs,
+  });
+  return runtime.engineStopPromise;
+}
+
+async function releaseEngine(runtime) {
+  if (typeof runtime.engineAdapter.close !== 'function') return;
+  if (!runtime.engineReleasePromise) {
+    try {
+      runtime.engineReleasePromise = Promise.resolve(runtime.engineAdapter.close()).then(
+        undefined,
+        (error) => {
+          reportLateFailure(runtime.cleanupFailureReporter, {
+            phase: 'engine_release',
+            kind: 'cleanup',
+            clusterId: runtime.machine.clusterId,
+            error,
+          });
+        }
+      );
+    } catch (error) {
+      reportLateFailure(runtime.cleanupFailureReporter, {
+        phase: 'engine_release',
+        kind: 'cleanup',
+        clusterId: runtime.machine.clusterId,
+        error,
+      });
+      runtime.engineReleasePromise = Promise.resolve();
+    }
+  }
+  await runtime.engineReleasePromise;
+}
+
+function waitForEngineCleanup(runtime) {
+  if (typeof runtime.engineAdapter.waitForCleanup === 'function') {
+    return Promise.resolve().then(() => runtime.engineAdapter.waitForCleanup());
+  }
+  return runtime.engineReleasePromise || runtime.engineStopPromise || Promise.resolve();
+}
+
+module.exports = { releaseEngine, stopEngine, waitForEngineCleanup };

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

@@ -0,0 +1,298 @@
+'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 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;
+  for (const artifact of artifacts) validateArtifactRef(artifact);
+  const stage = typeof resolver === 'function' ? resolver : resolver?.stage;
+  if (typeof stage !== 'function') throw new Error('ArtifactResolver must expose stage()');
+  const manifest = await runCancellable(
+    Promise.resolve().then(() => stage.call(resolver, artifacts, context)),
+    {
+      signal: context.signal,
+      cleanup: (lateManifest) => resolver?.cleanup?.(lateManifest, context),
+      reportFailure: context.reportCleanupFailure,
+      failureContext: { phase: 'artifact_staging', clusterId: context.clusterId },
+    }
+  );
+  if (manifest === CANCELLED) return CANCELLED;
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error('ArtifactResolver returned an invalid staged manifest');
+  }
+  return deepFreeze(manifest);
+}
+
+function createArtifactPreparation({
+  resolver,
+  artifacts,
+  clusterId,
+  getProfile,
+  signal,
+  reportFailure,
+}) {
+  return async (isolation) => {
+    const manifest = await stageArtifacts(resolver, artifacts, {
+      clusterId,
+      profile: getProfile(),
+      isolation,
+      signal,
+      reportCleanupFailure: reportFailure,
+    });
+    if (manifest === CANCELLED) throw new Error('Artifact staging was cancelled');
+    return manifest;
+  };
+}
+
+function defaultCleanupFailureReporter(failure) {
+  const message = failure.error instanceof Error ? failure.error.message : String(failure.error);
+  const cluster = failure.clusterId ? ` for cluster ${failure.clusterId}` : '';
+  process.emitWarning(
+    `Late ${failure.phase} ${failure.kind} failed${cluster}: ${message}`,
+    'ZeroshotCleanupWarning',
+    'ZEROSHOT_LEGACY_CLEANUP_FAILURE'
+  );
+}
+
+function reportReporterFailure(failure, reporterError) {
+  const original = failure.error instanceof Error ? failure.error.message : String(failure.error);
+  const reporting = reporterError instanceof Error ? reporterError.message : String(reporterError);
+  defaultCleanupFailureReporter({
+    ...failure,
+    error: new Error(`${original}; cleanup failure reporter also failed: ${reporting}`),
+  });
+}
+
+function reportLateFailure(reporter, failure) {
+  const selected = typeof reporter === 'function' ? reporter : defaultCleanupFailureReporter;
+  try {
+    const result = selected(Object.freeze(failure));
+    if (result && typeof result.then === 'function') {
+      result.then(undefined, (reporterError) => reportReporterFailure(failure, reporterError));
+    }
+  } catch (reporterError) {
+    reportReporterFailure(failure, reporterError);
+  }
+}
+
+async function observeCancelledOperation(operation, { cleanup, reportFailure, failureContext }) {
+  let lateValue;
+  try {
+    lateValue = await operation;
+  } catch (error) {
+    reportLateFailure(reportFailure, { ...failureContext, kind: 'operation', error });
+    return;
+  }
+  if (typeof cleanup !== 'function') return;
+  try {
+    await cleanup(lateValue);
+  } catch (error) {
+    reportLateFailure(reportFailure, { ...failureContext, kind: 'cleanup', error });
+  }
+}
+
+function observeLateSettlement(operation, options) {
+  observeCancelledOperation(operation, options).then(undefined, (error) =>
+    reportLateFailure(options.reportFailure, {
+      ...options.failureContext,
+      kind: 'operation',
+      error,
+    })
+  );
+}
+async function runCancellable(
+  value,
+  { signal, cleanup, reportFailure, failureContext = { phase: 'cancelled_operation' } } = {}
+) {
+  const operation = Promise.resolve(value);
+  if (!signal) return operation;
+  if (signal.aborted) {
+    observeLateSettlement(operation, { cleanup, reportFailure, failureContext });
+    return CANCELLED;
+  }
+
+  let removeAbortListener = () => {};
+  const cancellation = new Promise((resolve) => {
+    const onAbort = () => resolve(CANCELLED);
+    signal.addEventListener('abort', onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener('abort', onAbort);
+  });
+  const completed = operation.then((resolved) => ({ resolved }));
+  const winner = await Promise.race([completed, cancellation]);
+  removeAbortListener();
+  if (winner === CANCELLED) {
+    observeLateSettlement(operation, { cleanup, reportFailure, failureContext });
+    return CANCELLED;
+  }
+  return winner.resolved;
+}
+
+async function collectReceipts(sink, declared, context) {
+  if (!sink) return [];
+  if (context.signal?.aborted) return CANCELLED;
+  const collect = typeof sink === 'function' ? sink : sink.collect || sink.write;
+  if (typeof collect !== 'function') throw new Error('ArtifactReceiptSink must expose collect()');
+  const receipts = await runCancellable(
+    Promise.resolve().then(() => collect.call(sink, declared || [], context)),
+    {
+      signal: context.signal,
+      cleanup: (lateReceipts) => sink?.cleanup?.(lateReceipts, context),
+      reportFailure: context.reportCleanupFailure,
+      failureContext: { phase: 'receipt_collection', clusterId: context.clusterId },
+    }
+  );
+  if (receipts === CANCELLED) return CANCELLED;
+  if (!Array.isArray(receipts)) throw new Error('ArtifactReceiptSink must return an array');
+  for (const receipt of receipts) validateArtifactRef(receipt);
+  return receipts.map((receipt) => deepFreeze(cloneJson(receipt)));
+}
+
+function errorOutcome(code, reason) {
+  const outcome = { status: 'error', code, reason };
+  validateWorkerOutcome(outcome);
+  return Object.freeze(outcome);
+}
+
+async function stopEngineWithinBound({ engineAdapter, timers, shutdownMs }) {
+  let deadlineHandle = null;
+  let effective = false;
+  try {
+    const engineStop = Promise.resolve()
+      .then(() => engineAdapter.stop())
+      .then(
+        (stopResult) => stopResult?.effective !== false,
+        () => false
+      );
+    const deadline = new Promise((resolve) => {
+      deadlineHandle = timers.setTimeout(() => resolve(false), shutdownMs);
+    });
+    effective = await Promise.race([engineStop, deadline]);
+  } catch {
+    effective = false;
+  }
+  if (deadlineHandle !== null) {
+    try {
+      timers.clearTimeout(deadlineHandle);
+    } catch {
+      effective = false;
+    }
+  }
+  return effective;
+}
+
+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,
+  };
+}
+
+function assertProfilePlan(profile) {
+  if (!profile?.plan || !Object.isFrozen(profile.plan)) {
+    throw new Error('DeploymentProfileRegistry must return a frozen canonical plan');
+  }
+  if (profile.plan.isolation !== 'worktree' && profile.plan.isolation !== 'docker') {
+    throw new Error('Deployment profile resolved to non-isolated execution');
+  }
+}
+
+function assertFrozenProfile(profile) {
+  if (
+    !Object.isFrozen(profile) ||
+    !Object.isFrozen(profile.deployment) ||
+    !Object.isFrozen(profile.provider) ||
+    !Object.isFrozen(profile.bounds)
+  ) {
+    throw new Error('DeploymentProfileRegistry must return a frozen deployment descriptor');
+  }
+}
+
+function assertMatchingProfileHandles(profile, request) {
+  if (
+    profile.isolationProfile !== request.isolationProfile ||
+    profile.providerProfile !== request.providerProfile
+  ) {
+    throw new Error('DeploymentProfileRegistry returned mismatched profile handles');
+  }
+}
+
+function assertCanonicalPlan(plan) {
+  const canonical = resolveRunPlan({
+    docker: plan.isolation === 'docker',
+    worktree: plan.isolation === 'worktree',
+    pr: plan.delivery === 'pr',
+    ship: plan.delivery === 'ship',
+  });
+  if (
+    canonical.isolation !== plan.isolation ||
+    canonical.delivery !== plan.delivery ||
+    canonical.autoMerge !== plan.autoMerge
+  ) {
+    throw new Error('DeploymentProfileRegistry returned a non-canonical run plan');
+  }
+}
+
+function assertProfileBounds(bounds) {
+  for (const name of ['executionMs', 'shutdownMs', 'frameBytes']) {
+    if (!Number.isSafeInteger(bounds[name]) || bounds[name] <= 0) {
+      throw new Error(`Deployment profile bound ${name} must be a positive safe integer`);
+    }
+  }
+}
+
+function assertIsolatedProfile(profile, request) {
+  assertProfilePlan(profile);
+  assertFrozenProfile(profile);
+  assertMatchingProfileHandles(profile, request);
+  assertCanonicalPlan(profile.plan);
+  assertProfileBounds(profile.bounds);
+  return profile;
+}
+
+module.exports = {
+  CANCELLED,
+  assertIsolatedProfile,
+  collectReceipts,
+  createArtifactPreparation,
+  errorOutcome,
+  reportLateFailure,
+  resolveRuntimeDependencies,
+  runCancellable,
+  stageArtifacts,
+  stopEngineWithinBound,
+};

package/lib/cluster-worker/state-machine.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const {
+  TERMINAL_STATES,
+  validateLifecycleStatus,
+  validateTerminalReceipt,
+} = require('./contracts');
+const { deepFreeze } = require('./object-utils');
+
+const ALLOWED = Object.freeze({
+  idle: new Set(['starting']),
+  starting: new Set([
+    'running',
+    'stopping',
+    'completed',
+    'failed',
+    'timed_out',
+    'stopped',
+    'malformed',
+  ]),
+  running: new Set(['stopping', 'completed', 'failed', 'timed_out', 'stopped', 'malformed']),
+  stopping: new Set(['stopped', 'completed', 'failed', 'timed_out', 'malformed']),
+});
+
+class LiveEventIterator {
+  constructor(remove) {
+    this.remove = remove;
+    this.queue = [];
+    this.waiters = [];
+    this.closed = false;
+  }
+
+  push(value) {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) waiter({ value, done: false });
+    else this.queue.push(value);
+  }
+
+  next() {
+    if (this.queue.length > 0) return Promise.resolve({ value: this.queue.shift(), done: false });
+    if (this.closed) return Promise.resolve({ value: undefined, done: true });
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+
+  return() {
+    if (!this.closed) {
+      this.closed = true;
+      this.remove();
+      for (const waiter of this.waiters.splice(0)) waiter({ value: undefined, done: true });
+    }
+    return Promise.resolve({ value: undefined, done: true });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.remove();
+    for (const waiter of this.waiters.splice(0)) waiter({ value: undefined, done: true });
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+class LegacyWorkerStateMachine {
+  constructor({ clock = () => Date.now() } = {}) {
+    this.clock = clock;
+    this.state = 'idle';
+    this.clusterId = null;
+    this.sequence = 0;
+    this.stopRequested = false;
+    this.terminalReceipt = null;
+    this.subscribers = new Set();
+    this.resultPromise = new Promise((resolve) => {
+      this.resolveResult = resolve;
+    });
+  }
+
+  setClusterId(clusterId) {
+    if (this.clusterId && this.clusterId !== clusterId) {
+      throw new Error('Worker already owns a different cluster resource');
+    }
+    this.clusterId = clusterId;
+  }
+
+  status() {
+    return validateLifecycleStatus({
+      state: this.state,
+      clusterId: this.clusterId,
+      sequence: this.sequence,
+      stopRequested: this.stopRequested,
+      terminal: TERMINAL_STATES.includes(this.state),
+    });
+  }
+
+  events() {
+    let iterator;
+    iterator = new LiveEventIterator(() => this.subscribers.delete(iterator));
+    this.subscribers.add(iterator);
+    if (this.terminalReceipt) iterator.close();
+    return iterator;
+  }
+
+  transition(next, details) {
+    if (TERMINAL_STATES.includes(this.state)) return false;
+    const allowed = ALLOWED[this.state];
+    if (!allowed?.has(next))
+      throw new Error(`Invalid lifecycle transition ${this.state} -> ${next}`);
+    this.state = next;
+    this.sequence += 1;
+    const event = deepFreeze({
+      sequence: this.sequence,
+      state: next,
+      at: this.clock(),
+      ...(details === undefined ? {} : { details }),
+    });
+    for (const subscriber of this.subscribers) subscriber.push(event);
+    return true;
+  }
+
+  requestStop() {
+    this.stopRequested = true;
+    if (this.state === 'starting' || this.state === 'running') this.transition('stopping');
+  }
+
+  terminal(receipt) {
+    if (this.terminalReceipt) return false;
+    validateTerminalReceipt(receipt);
+    if (receipt.clusterId !== this.clusterId) {
+      throw new Error('Terminal receipt clusterId does not match owned resource');
+    }
+    const frozenReceipt = deepFreeze(receipt);
+    this.transition(receipt.state);
+    this.terminalReceipt = frozenReceipt;
+    this.resolveResult(this.terminalReceipt);
+    for (const subscriber of [...this.subscribers]) subscriber.close();
+    return true;
+  }
+
+  result() {
+    return this.resultPromise;
+  }
+}
+
+module.exports = { LegacyWorkerStateMachine };

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

@@ -0,0 +1,95 @@
+'use strict';
+
+const { validateLegacyShipResult, validateWorkerOutcome } = require('./contracts');
+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;
+  if (Object.prototype.hasOwnProperty.call(event, 'result')) {
+    validateLegacyShipResult(event.result);
+    summary = event.result.summary;
+    status = event.result.status;
+    declaredArtifacts = event.result.artifacts;
+  } else {
+    summary = event.summary;
+    validateLegacyShipResult({ summary, status, artifacts: [] });
+  }
+  const artifacts = await collectReceipts(options.artifactReceiptSink, declaredArtifacts, {
+    clusterId: options.machine.clusterId,
+    profile: options.getProfile(),
+    signal: options.signal,
+    reportCleanupFailure: options.cleanupFailureReporter,
+  });
+  if (artifacts === options.cancelled) return options.cancelled;
+  const result = { summary, status, artifacts };
+  validateLegacyShipResult(result);
+  return result;
+}
+
+function createTerminalNormalizer(options) {
+  let completionPending = false;
+
+  function terminalFailure(authority, state, code, reason) {
+    if (options.claimTerminalAuthority(authority)) {
+      options.machine.terminal(options.failureReceipt(state, code, reason));
+    }
+  }
+
+  async function normalizeCompletion(event) {
+    try {
+      const result = await Promise.race([resultFromEvent(event, options), options.terminalClaimed]);
+      if (result === options.cancelled) return;
+      if (options.claimTerminalAuthority('engine:complete')) {
+        options.machine.terminal({
+          state: 'completed',
+          clusterId: options.machine.clusterId,
+          finishedAt: options.clock(),
+          result: deepFreeze(cloneJson(result)),
+        });
+      }
+    } catch {
+      terminalFailure('engine:complete:malformed', 'malformed', 'malformed', 'malformed_result');
+    } finally {
+      completionPending = false;
+    }
+  }
+
+  function normalizeFailure(event) {
+    try {
+      validateWorkerOutcome({ status: 'error', code: event.code, reason: event.reason });
+      terminalFailure('engine:failed', 'failed', event.code, event.reason);
+    } catch {
+      terminalFailure('engine:failed:malformed', 'malformed', 'malformed', 'malformed_result');
+    }
+  }
+
+  function beginCompletion(event) {
+    if (completionPending) return;
+    completionPending = true;
+    normalizeCompletion(event).catch(() => undefined);
+  }
+
+  const terminalHandlers = {
+    failed: normalizeFailure,
+    malformed() {
+      terminalFailure('engine:malformed', 'malformed', 'malformed', 'malformed_result');
+    },
+  };
+
+  return function onEngineEvent(event) {
+    if (!event || typeof event !== 'object' || Array.isArray(event)) return;
+    if (event.type === 'running') {
+      if (options.machine.state === 'starting') options.machine.transition('running');
+      return;
+    }
+    if (options.isTerminal()) return;
+    if (event.type === 'complete') return beginCompletion(event);
+    if (completionPending) return;
+    terminalHandlers[event.type]?.(event);
+  };
+}
+
+module.exports = { createTerminalNormalizer };

package/lib/cluster-worker/worker-internals.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { releaseEngine, waitForEngineCleanup } = require('./runtime-engine');
+
+const RELEASE_WORKER = Symbol('releaseLegacyClusterWorker');
+const WAIT_FOR_WORKER_CLEANUP = Symbol('waitForLegacyClusterWorkerCleanup');
+
+function createWorkerFacade(runtime) {
+  return Object.freeze({
+    start: runtime.start.bind(runtime),
+    status: runtime.status.bind(runtime),
+    events: runtime.events.bind(runtime),
+    stop: runtime.stop.bind(runtime),
+    result: runtime.result.bind(runtime),
+    [RELEASE_WORKER]: () => releaseEngine(runtime),
+    [WAIT_FOR_WORKER_CLEANUP]: () => waitForEngineCleanup(runtime),
+  });
+}
+
+module.exports = { RELEASE_WORKER, WAIT_FOR_WORKER_CLEANUP, createWorkerFacade };