@the-open-engine/zeroshot 6.6.0 → 6.7.0

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

@@ -0,0 +1,300 @@
+'use strict';
+
+const { cloneJson } = require('./object-utils');
+
+const TERMINAL_TOPICS = new Set(['CLUSTER_COMPLETE', 'CLUSTER_FAILED']);
+
+function messageKey(message) {
+  return message.id ?? `${message.timestamp}:${message.topic}:${message.sender}`;
+}
+
+function terminalEventFromMessage(message) {
+  const data = message.content?.data || {};
+  if (message.topic === 'CLUSTER_COMPLETE') {
+    return {
+      type: 'complete',
+      summary: data.reason || message.content?.text,
+      ...(Object.prototype.hasOwnProperty.call(data, 'result') ? { result: data.result } : {}),
+      ...(Object.prototype.hasOwnProperty.call(data, 'artifacts')
+        ? { artifacts: data.artifacts }
+        : {}),
+    };
+  }
+  return {
+    type: 'failed',
+    summary: data.reason || message.content?.text,
+    code: data.code,
+    reason: data.workerReason,
+  };
+}
+
+function inputFromRequest(request, artifactManifest) {
+  if (request.source === 'issue') return { issue: request.issue };
+  if (request.source === 'prompt') return { text: request.prompt };
+  return {
+    text:
+      'Execute the task described by this registry-staged, byte-free artifact manifest. ' +
+      'Do not request interactive input.\n' +
+      JSON.stringify(artifactManifest),
+  };
+}
+
+function resolveOrchestrator(options) {
+  if (options.orchestrator) return options.orchestrator;
+  const Orchestrator = options.Orchestrator || require('../../src/orchestrator');
+  return new Orchestrator({
+    quiet: true,
+    ...(options.storageDir ? { storageDir: options.storageDir } : {}),
+    skipLoad: true,
+  });
+}
+
+class CurrentEngineAdapter {
+  constructor(options) {
+    this.options = options;
+    this.orchestrator = options.orchestrator || null;
+    this.startCluster = options.startCluster || null;
+    this.resource = null;
+    this.startPromise = null;
+    this.startSettled = false;
+    this.stopPromise = null;
+    this.cleanupPromise = null;
+    this.allocatedStopPromise = null;
+    this.stopRequested = false;
+    this.closed = false;
+    this.unsubscribe = null;
+    this.seen = new Set();
+    this.terminalObserved = false;
+    this.foldScheduled = false;
+  }
+
+  ensureRuntime() {
+    this.orchestrator ||= resolveOrchestrator(this.options);
+    this.startCluster ||= require('../start-cluster');
+  }
+
+  loadConfig(profile) {
+    const provider = profile.provider;
+    if (provider.config) {
+      const prepareClusterConfig =
+        this.startCluster.prepareClusterConfig || require('../start-cluster').prepareClusterConfig;
+      return prepareClusterConfig(
+        cloneJson(provider.config),
+        provider.settings || {},
+        provider.providerOverride || undefined
+      );
+    }
+    return this.startCluster.loadClusterConfig(
+      this.orchestrator,
+      provider.configPath || this.startCluster.resolveConfigPath(provider.configName),
+      provider.settings || {},
+      provider.providerOverride || undefined
+    );
+  }
+
+  startOptions(profile, clusterId) {
+    const provider = profile.provider;
+    return this.startCluster.buildTrustedStartOptions({
+      clusterId,
+      plan: profile.plan,
+      options: profile.deployment,
+      settings: provider.settings || {},
+      providerOverride: provider.providerOverride || undefined,
+      forceProvider: provider.forceProvider || undefined,
+    });
+  }
+
+  consume(message) {
+    if (
+      this.terminalObserved ||
+      message.cluster_id !== this.resource.clusterId ||
+      !TERMINAL_TOPICS.has(message.topic)
+    ) {
+      return;
+    }
+    const key = messageKey(message);
+    if (this.seen.has(key)) return;
+    this.seen.add(key);
+    this.terminalObserved = true;
+    this.resource.onEvent(terminalEventFromMessage(message));
+  }
+
+  foldDurableMessages() {
+    if (!this.resource.messageBus) return;
+    for (const message of this.resource.messageBus.getAll(this.resource.clusterId)) {
+      this.consume(message);
+    }
+  }
+
+  scheduleDurableFold(message) {
+    if (message.cluster_id !== this.resource.clusterId || !TERMINAL_TOPICS.has(message.topic)) {
+      return;
+    }
+    if (this.foldScheduled || this.terminalObserved) return;
+    this.foldScheduled = true;
+    Promise.resolve().then(() => {
+      this.foldScheduled = false;
+      if (!this.resource || this.terminalObserved) return;
+      try {
+        this.foldDurableMessages();
+      } catch {
+        this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+      }
+    });
+  }
+
+  async start({ request, profile, prepareArtifacts, clusterId, onEvent }) {
+    if (this.resource) throw new Error('Engine adapter owns one cluster resource');
+    this.ensureRuntime();
+    const config = this.loadConfig(profile);
+    const artifactInput = request.source === 'artifact';
+    if (artifactInput && typeof prepareArtifacts !== 'function') {
+      throw new Error('Artifact engine start requires prepareArtifacts()');
+    }
+    const input = artifactInput
+      ? { text: 'Artifact input is being prepared inside the allocated isolation.' }
+      : inputFromRequest(request);
+    const startOptions = this.startOptions(profile, clusterId);
+    let artifactsStaged = !artifactInput;
+    const options = artifactInput
+      ? {
+          ...startOptions,
+          async prepareIsolatedInput({ isolation }) {
+            const artifactManifest = await prepareArtifacts(isolation);
+            if (
+              !artifactManifest ||
+              typeof artifactManifest !== 'object' ||
+              Array.isArray(artifactManifest)
+            ) {
+              throw new Error('ArtifactResolver returned an invalid staged manifest');
+            }
+            artifactsStaged = true;
+            return inputFromRequest(request, artifactManifest).text;
+          },
+        }
+      : startOptions;
+    this.resource = {
+      clusterId,
+      messageBus: null,
+      onEvent,
+      shutdownMs: profile.bounds?.shutdownMs || 30_000,
+    };
+    try {
+      this.startPromise = Promise.resolve(this.orchestrator.start(config, input, options));
+      const started = await this.startPromise;
+      this.resource.clusterId = started.id;
+      this.resource.messageBus = started.messageBus;
+      this.unsubscribe = started.messageBus.subscribe((message) =>
+        this.scheduleDurableFold(message)
+      );
+      if (this.stopRequested) {
+        const stopResult = await this.stopPromise;
+        if (!stopResult.effective) await this.stopAllocatedCluster();
+      } else {
+        onEvent({ type: 'running' });
+      }
+      this.foldDurableMessages();
+      return Object.freeze({ clusterId: started.id, artifactsStaged });
+    } finally {
+      this.startSettled = true;
+    }
+  }
+
+  foldClusterState(cluster) {
+    if (!cluster) {
+      if (!this.terminalObserved) {
+        this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+      }
+      return 'released';
+    }
+    if (!this.terminalObserved && ['failed', 'stopped', 'killed'].includes(cluster.state)) {
+      this.resource.onEvent({ type: 'failed', code: 'crash', reason: 'declared_failure' });
+    } else if (cluster.state === 'running') {
+      this.resource.onEvent({ type: 'running' });
+    }
+    return cluster.state;
+  }
+
+  status() {
+    if (!this.resource) return null;
+    this.foldDurableMessages();
+    const cluster = this.orchestrator.getCluster(this.resource.clusterId);
+    if (!cluster && !this.startSettled) {
+      return Object.freeze({ clusterId: this.resource.clusterId, state: 'starting' });
+    }
+    const state = this.foldClusterState(cluster);
+    if (!cluster) return Object.freeze({ clusterId: this.resource.clusterId, state });
+    return Object.freeze({
+      clusterId: this.resource.clusterId,
+      state,
+      messageCount: cluster.ledger.count({ cluster_id: this.resource.clusterId }),
+      pidAliveDiagnostic: this.orchestrator.getStatus(this.resource.clusterId).isZombie !== true,
+    });
+  }
+
+  stop() {
+    if (!this.resource) throw new Error('Engine adapter has no cluster resource');
+    this.stopRequested = true;
+    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);
+      });
+      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);
+    this.allocatedStopPromise ||= Promise.resolve()
+      .then(() => this.orchestrator.stop(this.resource.clusterId))
+      .then(() => true);
+    return this.allocatedStopPromise;
+  }
+  async stopResource() {
+    this.cleanupPromise ||= this.waitForAllocatedCluster()
+      .then((cluster) => this.stopAllocatedCluster(cluster))
+      .catch(() => false)
+      .then((effective) => {
+        this.close();
+        return effective;
+      });
+    let deadlineHandle;
+    const deadline = new Promise((resolve) => {
+      deadlineHandle = setTimeout(() => resolve(false), this.resource.shutdownMs);
+    });
+    const effective = await Promise.race([this.cleanupPromise, deadline]);
+    clearTimeout(deadlineHandle);
+    return { effective };
+  }
+
+  waitForCleanup() {
+    return this.cleanupPromise || Promise.resolve();
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.orchestrator?.close();
+  }
+}
+
+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),
+  });
+}
+
+module.exports = { createCurrentEngineAdapter, inputFromRequest, terminalEventFromMessage };

package/lib/cluster-worker/executable.js

@@ -0,0 +1,229 @@
+'use strict';
+const { createLegacyClusterWorker } = require('./index');
+const { validateCommandFrame } = require('./contracts');
+const { DEFAULT_BOUNDS } = require('./profiles');
+const { RELEASE_WORKER, WAIT_FOR_WORKER_CLEANUP } = require('./worker-internals');
+
+const ERROR_CODES = Object.freeze({
+  SyntaxError: 'MALFORMED_JSON',
+  TypeError: 'INVALID_REQUEST',
+});
+
+function protocolError(error, fallback = 'WORKER_ERROR') {
+  return Object.freeze({
+    code: error?.code || ERROR_CODES[error?.name] || fallback,
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
+function writeFrame(output, frame) {
+  output.write(`${JSON.stringify(frame)}\n`);
+}
+
+async function pumpEvents({ id, iterator, state, output, diagnostics }) {
+  try {
+    for await (const event of iterator) writeFrame(output, { type: 'event', id, event });
+  } catch (error) {
+    diagnostics.write(`cluster-worker event stream failed: ${protocolError(error).message}\n`);
+  } finally {
+    state.eventPumps.delete(iterator);
+  }
+}
+
+function executeCommand(frame, worker, state, streams) {
+  if (frame.method === 'start') {
+    if (state.startSeen) {
+      const error = new Error('Worker process permits exactly one start command');
+      error.code = 'DUPLICATE_START';
+      throw error;
+    }
+    state.startSeen = true;
+    state.startPromise = Promise.resolve(worker.start(frame.params.request));
+    return state.startPromise;
+  }
+  if (frame.method === 'events') {
+    const iterator = worker.events();
+    state.eventPumps.add(iterator);
+    pumpEvents({ id: frame.id, iterator, state, ...streams });
+    return { subscribed: true };
+  }
+  if (state.startPromise && (frame.method === 'result' || frame.method === 'stop')) {
+    const terminal = Promise.race([
+      Promise.resolve().then(() => worker.result()),
+      state.startPromise.then(
+        () => new Promise(() => {}),
+        (error) => Promise.reject(error)
+      ),
+    ]);
+    if (frame.method === 'result') return terminal;
+    return Promise.race([terminal, Promise.resolve().then(() => worker.stop())]);
+  }
+  return worker[frame.method]();
+}
+
+function createCommandDispatcher({ worker, output, diagnostics }) {
+  const state = { eventPumps: new Set(), startSeen: false, startPromise: null };
+  const streams = { output, diagnostics };
+
+  async function dispatch(frame) {
+    const id =
+      frame && typeof frame === 'object' && !Array.isArray(frame) ? (frame.id ?? null) : null;
+    try {
+      validateCommandFrame(frame);
+      const result = await executeCommand(frame, worker, state, streams);
+      writeFrame(output, { type: 'response', id: frame.id, ok: true, result });
+    } catch (error) {
+      writeFrame(output, { type: 'response', id, ok: false, error: protocolError(error) });
+    }
+  }
+
+  function closeEvents() {
+    for (const iterator of [...state.eventPumps]) iterator.return();
+  }
+
+  return Object.freeze({
+    dispatch,
+    closeEvents,
+    hasStarted: () => state.startSeen,
+  });
+}
+
+function listenForFrames({ input, frameBytes, onFrame, onError, onClose }) {
+  let chunks = [];
+  let bytes = 0;
+  let discarding = false;
+
+  function finishLine() {
+    if (discarding) {
+      discarding = false;
+      chunks = [];
+      bytes = 0;
+      return;
+    }
+    let line = Buffer.concat(chunks, bytes);
+    if (line.at(-1) === 13) line = line.subarray(0, -1);
+    chunks = [];
+    bytes = 0;
+    if (line.length > 0) onFrame(line.toString('utf8'));
+  }
+
+  input.on('data', (inputChunk) => {
+    const chunk = Buffer.isBuffer(inputChunk) ? inputChunk : Buffer.from(inputChunk);
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const part = chunk.subarray(offset, end);
+      if (!discarding && bytes + part.length > frameBytes) {
+        discarding = true;
+        chunks = [];
+        bytes = 0;
+        onError();
+      } else if (!discarding && part.length > 0) {
+        chunks.push(part);
+        bytes += part.length;
+      }
+      if (newline === -1) break;
+      finishLine();
+      offset = newline + 1;
+    }
+  });
+  input.once('end', () => {
+    if (bytes > 0 || discarding) finishLine();
+    onClose();
+  });
+  input.once('error', onClose);
+}
+
+async function stopStartedWorker({ dispatcher, worker, diagnostics }) {
+  if (!dispatcher.hasStarted()) return;
+  await Promise.resolve(worker.stop()).catch((error) => {
+    diagnostics.write(`cluster-worker stop failed: ${protocolError(error).message}\n`);
+  });
+  await worker[WAIT_FOR_WORKER_CLEANUP]?.();
+}
+
+function createDeadline(milliseconds) {
+  let handle;
+  const promise = new Promise((resolve) => {
+    handle = setTimeout(resolve, milliseconds);
+  });
+  return { promise, cancel: () => clearTimeout(handle) };
+}
+
+function runClusterWorkerExecutable(options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const diagnostics = options.diagnostics || process.stderr;
+  const worker = options.worker || createLegacyClusterWorker(options.dependencies);
+  const frameBytes = options.frameBytes ?? DEFAULT_BOUNDS.frameBytes;
+  const shutdownMs = options.shutdownMs ?? DEFAULT_BOUNDS.shutdownMs;
+  for (const [name, value] of Object.entries({ frameBytes, shutdownMs })) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new TypeError(`${name} must be a positive safe integer`);
+    }
+  }
+  const dispatcher = createCommandDispatcher({ worker, output, diagnostics });
+  let closePromise = null;
+
+  function boundedStop() {
+    if (closePromise) return closePromise;
+    closePromise = (async () => {
+      dispatcher.closeEvents();
+      const deadline = createDeadline(shutdownMs);
+      await Promise.race([
+        stopStartedWorker({ dispatcher, worker, diagnostics }),
+        deadline.promise,
+      ]);
+      worker[RELEASE_WORKER]?.();
+      deadline.cancel();
+    })();
+    return closePromise;
+  }
+
+  function rejectOversizedFrame() {
+    writeFrame(output, {
+      type: 'response',
+      id: null,
+      ok: false,
+      error: { code: 'FRAME_TOO_LARGE', message: `Frame exceeds ${frameBytes} UTF-8 bytes` },
+    });
+  }
+
+  function acceptLine(line) {
+    if (closePromise) return;
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch (error) {
+      writeFrame(output, {
+        type: 'response',
+        id: null,
+        ok: false,
+        error: protocolError(error),
+      });
+      return;
+    }
+    dispatcher.dispatch(frame);
+  }
+
+  listenForFrames({
+    input,
+    frameBytes,
+    onFrame: acceptLine,
+    onError: rejectOversizedFrame,
+    onClose: () => boundedStop(),
+  });
+
+  return Object.freeze({
+    close: boundedStop,
+    dispatch: dispatcher.dispatch,
+  });
+}
+
+module.exports = {
+  createCommandDispatcher,
+  listenForFrames,
+  protocolError,
+  runClusterWorkerExecutable,
+};