@the-open-engine/zeroshot 6.5.0 → 6.7.0

package/lib/cluster-worker/index.d.ts

@@ -0,0 +1,227 @@
+export type ArtifactRef = {
+  artifactId: string;
+  sha256: string;
+  byteLength: number;
+  mediaType: string;
+  typeId: string;
+  producer: { node: string; worker: string };
+  lineage: { generation: number; runId: string; attempt: number };
+  redaction: 'public' | 'internal' | 'confidential' | 'restricted';
+};
+
+type RequestBase = {
+  isolationProfile: string;
+  providerProfile: string;
+};
+
+export type LegacyShipRequest = RequestBase &
+  (
+    | { source: 'issue'; issue: string; prompt?: null; artifacts: [] }
+    | { source: 'prompt'; prompt: string; issue?: null; artifacts: [] }
+    | { source: 'artifact'; issue?: null; prompt?: null; artifacts: ArtifactRef[] }
+  );
+
+export type LegacyShipResult = {
+  summary: string;
+  status: 'succeeded' | 'failed';
+  artifacts: ArtifactRef[];
+};
+
+export type LifecycleState =
+  | 'idle'
+  | 'starting'
+  | 'running'
+  | 'stopping'
+  | 'completed'
+  | 'failed'
+  | 'timed_out'
+  | 'stopped'
+  | 'malformed';
+
+export type LifecycleStatus = {
+  state: LifecycleState;
+  clusterId: string | null;
+  sequence: number;
+  stopRequested: boolean;
+  terminal: boolean;
+};
+
+export type WorkerError =
+  | {
+      status: 'error';
+      code: 'timeout' | 'crash' | 'malformed' | 'refusal';
+      reason: 'declared_failure';
+    }
+  | {
+      status: 'error';
+      code: 'refusal';
+      reason: 'policy_denied' | 'interactive_input_required' | 'authentication_required';
+    }
+  | { status: 'error'; code: 'malformed'; reason: 'malformed_result' };
+
+export type TerminalReceipt =
+  | { state: 'completed'; clusterId: string; finishedAt: number; result: LegacyShipResult }
+  | {
+      state: 'stopped';
+      clusterId: string;
+      finishedAt: number;
+      stop: { requested: true; effective: boolean; externalEffectsRolledBack: false };
+    }
+  | {
+      state: 'failed' | 'timed_out' | 'malformed';
+      clusterId: string;
+      finishedAt: number;
+      outcome: WorkerError;
+    };
+
+export type LifecycleEvent = {
+  sequence: number;
+  state: Exclude<LifecycleState, 'idle'>;
+  at: number;
+  details?: unknown;
+};
+
+export type RunPlan = Readonly<{
+  isolation: 'worktree' | 'docker';
+  delivery: 'none' | 'pr' | 'ship';
+  autoMerge: boolean;
+}>;
+
+export type ExecutionBounds = Readonly<{
+  executionMs: number;
+  shutdownMs: number;
+  frameBytes: number;
+}>;
+
+export type ResolvedDeploymentProfile = Readonly<{
+  isolationProfile: string;
+  providerProfile: string;
+  plan: RunPlan;
+  deployment: Readonly<Record<string, unknown>>;
+  provider: Readonly<Record<string, unknown>>;
+  bounds: ExecutionBounds;
+}>;
+
+export type CancellationContext = Readonly<{ signal: AbortSignal }>;
+
+export type CleanupFailure = Readonly<{
+  phase: 'profile_resolution' | 'artifact_staging' | 'receipt_collection';
+  kind: 'operation' | 'cleanup';
+  clusterId: string | null;
+  error: unknown;
+}>;
+
+export type IsolationWorkspace = Readonly<{
+  kind: 'worktree' | 'docker';
+  hostRoot: string;
+  runtimeRoot: string;
+}>;
+
+export interface DeploymentProfileRegistry {
+  readonly bounds?: ExecutionBounds;
+  resolve(
+    isolationProfile: string,
+    providerProfile: string,
+    context: CancellationContext
+  ): ResolvedDeploymentProfile | Promise<ResolvedDeploymentProfile>;
+  release?(profile: ResolvedDeploymentProfile, context: CancellationContext): void | Promise<void>;
+}
+
+export interface ArtifactResolver {
+  stage(
+    artifacts: readonly ArtifactRef[],
+    context: Readonly<{
+      clusterId: string;
+      profile: ResolvedDeploymentProfile;
+      isolation: IsolationWorkspace;
+      signal: AbortSignal;
+    }>
+  ): Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+  cleanup?(
+    manifest: Readonly<Record<string, unknown>>,
+    context: Readonly<{
+      clusterId: string;
+      profile: ResolvedDeploymentProfile;
+      isolation: IsolationWorkspace;
+      signal: AbortSignal;
+    }>
+  ): void | Promise<void>;
+}
+
+export interface ArtifactReceiptSink {
+  collect(
+    declared: readonly unknown[],
+    context: Readonly<{
+      clusterId: string;
+      profile: ResolvedDeploymentProfile;
+      signal: AbortSignal;
+    }>
+  ): readonly ArtifactRef[] | Promise<readonly ArtifactRef[]>;
+  cleanup?(
+    receipts: readonly ArtifactRef[],
+    context: Readonly<{
+      clusterId: string;
+      profile: ResolvedDeploymentProfile;
+      signal: AbortSignal;
+    }>
+  ): void | Promise<void>;
+}
+
+export type EngineEvent =
+  | { type: 'running' }
+  | ({ type: 'complete'; artifacts?: readonly unknown[] } & (
+      | { summary: string; result?: never }
+      | { result: LegacyShipResult; summary?: string }
+    ))
+  | ({ type: 'failed' } & Omit<WorkerError, 'status'>)
+  | { type: 'malformed' };
+
+export interface EngineAdapter {
+  start(input: {
+    request: LegacyShipRequest;
+    profile: ResolvedDeploymentProfile;
+    prepareArtifacts?(isolation: IsolationWorkspace): Promise<Readonly<Record<string, unknown>>>;
+    clusterId: string;
+    onEvent(event: EngineEvent): void;
+  }):
+    | { clusterId?: string; artifactsStaged?: boolean }
+    | Promise<{ clusterId?: string; artifactsStaged?: boolean }>;
+  status?(): Readonly<Record<string, unknown>> | null;
+  stop(): { effective?: boolean } | Promise<{ effective?: boolean }>;
+  waitForCleanup?(): void | Promise<void>;
+  close?(): void | Promise<void>;
+}
+
+export type LegacyClusterWorkerDependencies = {
+  profileRegistry?: DeploymentProfileRegistry;
+  artifactResolver?: ArtifactResolver | ArtifactResolver['stage'];
+  artifactReceiptSink?: ArtifactReceiptSink | ArtifactReceiptSink['collect'];
+  engineAdapter?: EngineAdapter;
+  clock?: () => number;
+  timers?: {
+    setTimeout(callback: () => void, milliseconds: number): unknown;
+    clearTimeout(handle: unknown): void;
+  };
+  idFactory?: () => string;
+  cleanupFailureReporter?: (failure: CleanupFailure) => void | Promise<void>;
+};
+
+export interface LegacyClusterWorker {
+  start(request: LegacyShipRequest): Promise<LifecycleStatus>;
+  status(): LifecycleStatus;
+  events(): AsyncIterableIterator<LifecycleEvent>;
+  stop(): Promise<TerminalReceipt>;
+  result(): Promise<TerminalReceipt>;
+}
+
+export function createLegacyClusterWorker(
+  dependencies?: LegacyClusterWorkerDependencies
+): LegacyClusterWorker;
+
+export function createDeploymentProfileRegistry(options?: {
+  isolationProfiles?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  providerProfiles?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  bounds?: Partial<ExecutionBounds>;
+}): DeploymentProfileRegistry;
+
+export function createCurrentEngineAdapter(options?: object): EngineAdapter;

package/lib/cluster-worker/index.js

@@ -0,0 +1,294 @@
+'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 { releaseEngine, stopEngine } = require('./runtime-engine');
+const { LegacyWorkerStateMachine } = require('./state-machine');
+const { createTerminalNormalizer } = require('./terminal-normalizer');
+const { createWorkerFacade } = require('./worker-internals');
+
+class LegacyClusterWorkerRuntime {
+  constructor(dependencies) {
+    Object.assign(this, resolveRuntimeDependencies(dependencies));
+    this.machine = new LegacyWorkerStateMachine({ clock: this.clock });
+    this.startClaimed = false;
+    this.profile = null;
+    this.timeoutHandle = null;
+    this.timeoutGeneration = 0;
+    this.executionStartedAt = null;
+    this.terminalAuthority = null;
+    this.engineStartAttempted = false;
+    this.engineStopPromise = null;
+    this.engineReleasePromise = null;
+    this.preparationController = new AbortController();
+    this.terminalClaimed = new Promise((resolve) => {
+      this.resolveTerminalClaimed = resolve;
+    });
+    this.onEngineEvent = createTerminalNormalizer({
+      machine: this.machine,
+      clock: this.clock,
+      artifactReceiptSink: this.artifactReceiptSink,
+      getProfile: () => this.profile,
+      claimTerminalAuthority: (authority) => this.claimTerminalAuthority(authority),
+      failureReceipt: (state, code, reason) => this.failureReceipt(state, code, reason),
+      isTerminal: () => this.terminalAuthority !== null || Boolean(this.machine.terminalReceipt),
+      terminalClaimed: this.terminalClaimed,
+      signal: this.preparationController.signal,
+      cancelled: CANCELLED,
+      cleanupFailureReporter: this.cleanupFailureReporter,
+    });
+  }
+  clearExecutionTimeout() {
+    this.timeoutGeneration += 1;
+    if (this.timeoutHandle !== null) {
+      try {
+        this.timers.clearTimeout(this.timeoutHandle);
+      } catch {
+        // The generation guard still makes a stale callback inert.
+      }
+    }
+    this.timeoutHandle = null;
+  }
+  armExecutionTimeout(milliseconds) {
+    this.clearExecutionTimeout();
+    const generation = this.timeoutGeneration;
+    const elapsed = Math.max(0, this.clock() - this.executionStartedAt);
+    const remaining = Math.max(0, milliseconds - elapsed);
+    this.timeoutHandle = this.timers.setTimeout(() => {
+      if (generation !== this.timeoutGeneration) return;
+      this.timeoutHandle = null;
+      if (this.claimTerminalAuthority('timeout')) {
+        this.machine.terminal(this.failureReceipt('timed_out', 'timeout', 'declared_failure'));
+        if (this.engineStartAttempted) this.stopEngine().catch(() => undefined);
+      }
+    }, remaining);
+  }
+  initialExecutionBound() {
+    const milliseconds =
+      this.profile?.bounds.executionMs ?? this.profileRegistry?.bounds?.executionMs;
+    return Number.isSafeInteger(milliseconds) && milliseconds > 0
+      ? milliseconds
+      : DEFAULT_BOUNDS.executionMs;
+  }
+  cancelPreparation() {
+    this.preparationController.abort();
+  }
+  racePreparation(value, cleanup) {
+    return runCancellable(value, {
+      signal: this.preparationController.signal,
+      cleanup,
+      reportFailure: this.cleanupFailureReporter,
+      failureContext: {
+        phase: 'profile_resolution',
+        clusterId: this.machine.clusterId,
+      },
+    });
+  }
+  failureReceipt(state, code, reason) {
+    return {
+      state,
+      clusterId: this.machine.clusterId,
+      finishedAt: this.clock(),
+      outcome: errorOutcome(code, reason),
+    };
+  }
+  claimTerminalAuthority(authority) {
+    if (this.terminalAuthority !== null || this.machine.terminalReceipt) return false;
+    this.terminalAuthority = authority;
+    this.clearExecutionTimeout();
+    this.cancelPreparation();
+    this.resolveTerminalClaimed(CANCELLED);
+    return true;
+  }
+  failEngineStatus() {
+    if (this.claimTerminalAuthority('engine:status')) {
+      this.machine.terminal(this.failureReceipt('failed', 'crash', 'declared_failure'));
+    }
+  }
+  async prepareStart(request, clusterId, profileResolution) {
+    if (!this.profile) {
+      const profileContext = Object.freeze({ signal: this.preparationController.signal });
+      const resolvedProfile = await this.racePreparation(profileResolution, (profile) =>
+        this.profileRegistry.release?.(profile, profileContext)
+      );
+      if (resolvedProfile === CANCELLED) return CANCELLED;
+      this.profile = assertIsolatedProfile(resolvedProfile, request);
+    }
+    this.armExecutionTimeout(this.profile.bounds.executionMs);
+    if (this.terminalAuthority !== null) return CANCELLED;
+    return { clusterId };
+  }
+  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();
+    } 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;
+    }
+  }
+  beginLifecycle() {
+    const clusterId = this.idFactory();
+    if (typeof clusterId !== 'string' || !clusterId) {
+      throw new Error('idFactory returned invalid id');
+    }
+    this.machine.setClusterId(clusterId);
+    this.machine.transition('starting');
+    this.executionStartedAt = this.clock();
+    this.armExecutionTimeout(this.initialExecutionBound());
+    return clusterId;
+  }
+  async start(request) {
+    if (this.startClaimed) throw new Error('Worker facade permits exactly one start');
+    const requestSnapshot = deepFreeze(cloneJson(request));
+    validateLegacyShipRequest(requestSnapshot);
+    if (requestSnapshot.source === 'artifact' && !this.artifactResolver) {
+      throw new Error('ArtifactResolver is required for artifact input');
+    }
+    // Claim synchronously so concurrent calls cannot allocate two resources.
+    this.startClaimed = true;
+    let clusterId;
+    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 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;
+    }
+  }
+  status() {
+    if (
+      this.engineStartAttempted &&
+      this.machine.clusterId &&
+      !this.machine.terminalReceipt &&
+      typeof this.engineAdapter.status === 'function'
+    ) {
+      try {
+        const diagnostic = this.engineAdapter.status();
+        if (diagnostic && typeof diagnostic.then === 'function') {
+          diagnostic.then(undefined, () => this.failEngineStatus());
+          throw new TypeError('EngineAdapter.status() must return synchronously');
+        }
+      } catch (error) {
+        this.failEngineStatus();
+        if (!this.machine.terminalReceipt) throw error;
+      }
+    }
+    return this.machine.status();
+  }
+  events() {
+    return this.machine.events();
+  }
+  stopEngine() {
+    return stopEngine(this);
+  }
+  async releaseEngine() {
+    await releaseEngine(this);
+  }
+  async stop() {
+    if (!this.startClaimed) throw new Error('Worker has not started');
+    if (this.machine.terminalReceipt) {
+      const cleanupEffective = this.engineStopPromise ? await this.engineStopPromise : true;
+      if (cleanupEffective) await this.releaseEngine();
+      return this.machine.terminalReceipt;
+    }
+    if (!this.claimTerminalAuthority('stop')) return this.machine.result();
+    this.machine.requestStop();
+    const effective = this.engineStartAttempted ? await this.stopEngine() : true;
+    this.machine.terminal({
+      state: 'stopped',
+      clusterId: this.machine.clusterId,
+      finishedAt: this.clock(),
+      stop: {
+        requested: true,
+        effective,
+        externalEffectsRolledBack: false,
+      },
+    });
+    if (effective) await this.releaseEngine();
+    return this.machine.terminalReceipt;
+  }
+  result() {
+    if (!this.startClaimed) throw new Error('Worker has not started');
+    return this.machine.result();
+  }
+}
+
+function createLegacyClusterWorker(dependencies = {}) {
+  return createWorkerFacade(new LegacyClusterWorkerRuntime(dependencies));
+}
+
+module.exports = {
+  createLegacyClusterWorker,
+  createDeploymentProfileRegistry,
+  createCurrentEngineAdapter,
+};

package/lib/cluster-worker/object-utils.js

@@ -0,0 +1,17 @@
+'use strict';
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object') return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.isFrozen(value) ? value : Object.freeze(value);
+}
+
+function cloneJson(value) {
+  if (Array.isArray(value)) return value.map(cloneJson);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cloneJson(child)]));
+  }
+  return value;
+}
+
+module.exports = { cloneJson, deepFreeze };

package/lib/cluster-worker/process-stdio.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const util = require('node:util');
+
+function redirectConsoleToStderr() {
+  console.log = (...args) => process.stderr.write(`${util.format(...args)}\n`);
+  console.info = console.log;
+  console.debug = console.log;
+}
+
+function bindProcessLifecycle(runtime) {
+  let closing = null;
+  const closeAndRelease = () => {
+    closing ||= Promise.resolve()
+      .then(() => runtime.close())
+      .then(
+        () => {
+          process.exitCode = 0;
+          process.exit(0);
+        },
+        (error) => {
+          process.stderr.write(`cluster-worker shutdown failed: ${error.message}\n`);
+          process.exitCode = 1;
+          process.exit(1);
+        }
+      );
+  };
+  const closeFromSignal = () => {
+    process.stdin.pause();
+    process.stdin.destroy();
+    closeAndRelease();
+  };
+  process.stdin.once('end', closeAndRelease);
+  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, closeFromSignal);
+}
+
+module.exports = { bindProcessLifecycle, redirectConsoleToStderr };

package/lib/cluster-worker/profiles.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { resolveRunPlan } = require('../run-plan');
+const { deepFreeze } = require('./object-utils');
+
+const DEFAULT_BOUNDS = Object.freeze({
+  executionMs: 60 * 60 * 1000,
+  shutdownMs: 30 * 1000,
+  frameBytes: 64 * 1024,
+});
+
+const DEFAULT_ISOLATION_PROFILES = Object.freeze({
+  'isolation.worktree@1': Object.freeze({ worktree: true }),
+  'isolation.docker@1': Object.freeze({ docker: true }),
+  'isolation.pr@1': Object.freeze({ pr: true }),
+  'isolation.ship@1': Object.freeze({ ship: true }),
+});
+
+const DEFAULT_PROVIDER_PROFILES = Object.freeze({
+  'provider.default@1': Object.freeze({
+    configName: 'conductor-bootstrap',
+    providerOverride: null,
+    settings: Object.freeze({}),
+  }),
+});
+
+function own(map, key) {
+  return Object.prototype.hasOwnProperty.call(map, key) ? map[key] : null;
+}
+
+function validateBounds(bounds) {
+  for (const name of ['executionMs', 'shutdownMs', 'frameBytes']) {
+    if (!Number.isSafeInteger(bounds[name]) || bounds[name] <= 0) {
+      throw new Error(`Deployment bound ${name} must be a positive safe integer`);
+    }
+  }
+}
+
+function createDeploymentProfileRegistry(options = {}) {
+  const isolationProfiles = options.isolationProfiles || DEFAULT_ISOLATION_PROFILES;
+  const providerProfiles = options.providerProfiles || DEFAULT_PROVIDER_PROFILES;
+  const defaultBounds = { ...DEFAULT_BOUNDS, ...(options.bounds || {}) };
+  validateBounds(defaultBounds);
+  const bounds = deepFreeze(defaultBounds);
+
+  return Object.freeze({
+    bounds,
+    resolve(isolationHandle, providerHandle) {
+      const deployment = own(isolationProfiles, isolationHandle);
+      if (!deployment) throw new Error(`Unknown isolation profile: ${String(isolationHandle)}`);
+      const provider = own(providerProfiles, providerHandle);
+      if (!provider) throw new Error(`Unknown provider profile: ${String(providerHandle)}`);
+
+      const plan = resolveRunPlan(deployment);
+      if (plan.isolation !== 'worktree' && plan.isolation !== 'docker') {
+        throw new Error(`Isolation profile ${isolationHandle} resolves to non-isolated execution`);
+      }
+      const resolvedBounds = {
+        ...defaultBounds,
+        ...(deployment.bounds || {}),
+        ...(provider.bounds || {}),
+      };
+      validateBounds(resolvedBounds);
+      return deepFreeze({
+        isolationProfile: isolationHandle,
+        providerProfile: providerHandle,
+        plan,
+        deployment: { ...deployment },
+        provider: { ...provider },
+        bounds: resolvedBounds,
+      });
+    },
+  });
+}
+
+module.exports = {
+  DEFAULT_BOUNDS,
+  DEFAULT_ISOLATION_PROFILES,
+  DEFAULT_PROVIDER_PROFILES,
+  createDeploymentProfileRegistry,
+};