@the-open-engine/zeroshot 6.30.2 → 6.31.1

package/src/agent-cli-provider/omp/sdk-process-private-runtime.ts

@@ -0,0 +1,249 @@
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+
+import {
+  OMP_SDK_BACKEND_VERSION,
+  OMP_SDK_BUN_VERSION,
+  type OmpSdkCollectedTerminal,
+  type OmpSdkProtocolProgressFrame,
+} from './sdk-protocol';
+import type { PreparedSingleAgentProviderCommand } from '../single-agent-runtime';
+import type {
+  OmpSdkCleanupAttestation,
+  OmpSdkContainmentRequirement,
+  OmpSdkExecutionIdentity,
+  OmpSdkSemanticIdentity,
+  PreparedEnvironmentPolicy,
+  PreparedPrivateArtifacts,
+  PreparedProviderInvoke,
+} from '../types';
+import type { ProcessResult, ProcessRunnerOptions } from '../process-runner';
+import { OmpSdkProcessRunnerError } from './sdk-process-error';
+
+export { credentialPayload, redactDiagnostic } from './sdk-process-credentials';
+export { OmpSdkProcessRunnerError } from './sdk-process-error';
+
+const PRIVATE_ROOT_NAME = /^zeroshot-omp-sdk-[A-Za-z0-9_-]+$/u;
+const PRIVATE_ENV_NAMES = new Set([
+  'HOME',
+  'XDG_CACHE_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_STATE_HOME',
+  'PI_CODING_AGENT_DIR',
+]);
+const MINIMAL_ENV_NAMES = new Set([
+  'ALL_PROXY',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'LANG',
+  'LC_ALL',
+  'NO_PROXY',
+  'PATH',
+  'SSL_CERT_DIR',
+  'SSL_CERT_FILE',
+  'TZ',
+]);
+
+export interface OmpSdkPreparedInvocation extends PreparedSingleAgentProviderCommand {
+  readonly invoke: PreparedProviderInvoke & {
+    readonly lane: 'spawn';
+    readonly parser: 'omp-sdk-ndjson';
+    readonly ptyEligible: false;
+    readonly strictTerminal: true;
+  };
+  readonly environmentPolicy: PreparedEnvironmentPolicy;
+  readonly credentialNames: readonly string[];
+  readonly privateArtifacts: PreparedPrivateArtifacts;
+  readonly containmentRequirement: OmpSdkContainmentRequirement;
+  readonly executionIdentity: OmpSdkExecutionIdentity;
+  readonly semanticIdentity: OmpSdkSemanticIdentity;
+}
+export interface OmpSdkProcessRunnerOptions extends ProcessRunnerOptions {
+  readonly onProgress?: (frame: OmpSdkProtocolProgressFrame) => void;
+  readonly reapTimeoutMs?: number;
+}
+export interface OmpSdkProcessResult extends ProcessResult {
+  readonly terminal: OmpSdkCollectedTerminal;
+  readonly progress: readonly OmpSdkProtocolProgressFrame[];
+  readonly diagnosticStderr: string;
+  readonly cleanupAttestation: OmpSdkCleanupAttestation;
+}
+export interface OmpSdkRunningProcess {
+  readonly pid: number;
+  readonly result: Promise<OmpSdkProcessResult>;
+  cancel(): void;
+}
+export interface PrivateRuntime {
+  readonly root: string;
+  readonly requestPath: string;
+  readonly home: string;
+  readonly xdgConfig: string;
+  readonly xdgCache: string;
+  readonly xdgData: string;
+  readonly xdgState: string;
+  readonly piDirectory: string;
+}
+
+export function assertPrepared(
+  prepared: PreparedSingleAgentProviderCommand
+): asserts prepared is OmpSdkPreparedInvocation {
+  const valid =
+    prepared.invoke.lane === 'spawn' &&
+    prepared.invoke.parser === 'omp-sdk-ndjson' &&
+    prepared.invoke.ptyEligible === false &&
+    prepared.invoke.strictTerminal === true &&
+    prepared.environmentPolicy?.inherit === 'minimal' &&
+    prepared.privateArtifacts?.owned === true &&
+    prepared.containmentRequirement?.required === true &&
+    prepared.executionIdentity?.backend === 'omp-sdk' &&
+    prepared.semanticIdentity !== undefined &&
+    Array.isArray(prepared.credentialNames);
+  if (!valid)
+    throw new OmpSdkProcessRunnerError(
+      'protocol-error',
+      'OMP SDK spawn requires a complete authoritative prepared invocation.'
+    );
+  if (
+    prepared.executionIdentity.backendVersion !== OMP_SDK_BACKEND_VERSION ||
+    prepared.executionIdentity.runtime.name !== 'bun' ||
+    prepared.executionIdentity.runtime.version !== OMP_SDK_BUN_VERSION ||
+    prepared.executionIdentity.transport !== 'sdk'
+  ) {
+    throw new OmpSdkProcessRunnerError(
+      'protocol-error',
+      'OMP SDK prepared identity does not match the pinned runtime.'
+    );
+  }
+}
+export function assertHostContainment(requirement: OmpSdkContainmentRequirement): void {
+  if (
+    requirement.mode !== 'host-process-tree' ||
+    process.platform !== 'linux' ||
+    (process.arch !== 'x64' && process.arch !== 'arm64')
+  ) {
+    throw new OmpSdkProcessRunnerError(
+      'containment-error',
+      'OMP SDK host spawn requires the packaged Linux subreaper/pidfd supervisor; container invocations require the container spawn owner.'
+    );
+  }
+}
+function pathIsWithin(root: string, candidate: string): boolean {
+  const fragment = relative(root, candidate);
+  return (
+    fragment.length > 0 &&
+    fragment !== '..' &&
+    !fragment.startsWith(`..${sep}`) &&
+    !isAbsolute(fragment)
+  );
+}
+export async function makePrivateRuntime(
+  artifacts: PreparedPrivateArtifacts
+): Promise<PrivateRuntime> {
+  if (!artifacts.owned || !isAbsolute(artifacts.root) || !isAbsolute(artifacts.requestPath)) {
+    throw new OmpSdkProcessRunnerError(
+      'cleanup-error',
+      'OMP SDK private artifact ownership is invalid.'
+    );
+  }
+  const root = resolve(artifacts.root);
+  const requestPath = resolve(artifacts.requestPath);
+  if (
+    root === parse(root).root ||
+    root === resolve(tmpdir()) ||
+    root === resolve(process.cwd()) ||
+    dirname(root) !== resolve(tmpdir()) ||
+    !PRIVATE_ROOT_NAME.test(basename(root)) ||
+    !pathIsWithin(root, requestPath) ||
+    dirname(requestPath) !== root
+  ) {
+    throw new OmpSdkProcessRunnerError(
+      'cleanup-error',
+      'OMP SDK private artifact boundary is unsafe.'
+    );
+  }
+  const [rootStat, requestStat, canonicalRoot, canonicalRequest] = await Promise.all([
+    fs.lstat(root),
+    fs.lstat(requestPath),
+    fs.realpath(root),
+    fs.realpath(requestPath),
+  ]);
+  if (
+    !rootStat.isDirectory() ||
+    rootStat.isSymbolicLink() ||
+    (rootStat.mode & 0o077) !== 0 ||
+    !requestStat.isFile() ||
+    requestStat.isSymbolicLink() ||
+    (requestStat.mode & 0o077) !== 0 ||
+    canonicalRoot !== root ||
+    canonicalRequest !== requestPath
+  ) {
+    throw new OmpSdkProcessRunnerError(
+      'cleanup-error',
+      'OMP SDK private artifacts are not owner-only regular paths.'
+    );
+  }
+  await Promise.all(
+    ['home', 'xdg-config', 'xdg-cache', 'xdg-data', 'xdg-state', 'pi'].map((name) =>
+      fs.mkdir(join(root, name), { mode: 0o700, recursive: false })
+    )
+  );
+  return {
+    root,
+    requestPath,
+    home: join(root, 'home'),
+    xdgConfig: join(root, 'xdg-config'),
+    xdgCache: join(root, 'xdg-cache'),
+    xdgData: join(root, 'xdg-data'),
+    xdgState: join(root, 'xdg-state'),
+    piDirectory: join(root, 'pi'),
+  };
+}
+export async function removePrivateRoot(runtime: PrivateRuntime): Promise<void> {
+  try {
+    if ((await fs.realpath(runtime.root)) !== runtime.root)
+      throw new Error('private root changed identity');
+    await fs.rm(runtime.root, { force: true, maxRetries: 3, recursive: true });
+    try {
+      await fs.lstat(runtime.root);
+      throw new Error('private root remains');
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+    }
+  } catch (error) {
+    throw new OmpSdkProcessRunnerError(
+      'cleanup-error',
+      'OMP SDK owned private root could not be removed.',
+      { cause: error }
+    );
+  }
+}
+
+export function childEnvironment(
+  policy: PreparedEnvironmentPolicy,
+  runtime: PrivateRuntime
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(policy.values)) {
+    const normalized = name.toUpperCase();
+    if (
+      !MINIMAL_ENV_NAMES.has(normalized) ||
+      PRIVATE_ENV_NAMES.has(normalized) ||
+      /(?:^|_)(?:AUTH|CREDENTIAL|KEY|PASSWORD|SECRET|TOKEN)(?:_|$)/i.test(name)
+    ) {
+      throw new OmpSdkProcessRunnerError(
+        'protocol-error',
+        `OMP SDK minimal environment contains unsupported key ${name}.`
+      );
+    }
+    env[name] = value;
+  }
+  env.HOME = runtime.home;
+  env.XDG_CONFIG_HOME = runtime.xdgConfig;
+  env.XDG_CACHE_HOME = runtime.xdgCache;
+  env.XDG_DATA_HOME = runtime.xdgData;
+  env.XDG_STATE_HOME = runtime.xdgState;
+  env.PI_CODING_AGENT_DIR = runtime.piDirectory;
+  return env;
+}

package/src/agent-cli-provider/omp/sdk-process-result.ts

@@ -0,0 +1,181 @@
+import { parseOmpSdkSupervisorAttestation } from './sdk-runtime';
+import type {
+  OmpSdkCollectedTerminal,
+  OmpSdkProtocolCollector,
+  OmpSdkSidecarRequest,
+} from './sdk-protocol';
+import type { OmpSdkCleanupAttestation } from '../types';
+import { cancelledTerminal, type ChildOutcome } from './sdk-process-io';
+import {
+  OmpSdkProcessRunnerError,
+  redactDiagnostic,
+  removePrivateRoot,
+  type OmpSdkProcessResult,
+  type OmpSdkProcessRunnerOptions,
+  type PrivateRuntime,
+} from './sdk-process-private-runtime';
+
+export interface OmpSdkSupervisionState {
+  timedOut: boolean;
+  protocolError: unknown;
+  readonly stderrChunks: Buffer[];
+  readonly attestationChunks: Buffer[];
+  timeout: NodeJS.Timeout | undefined;
+}
+
+interface OmpSdkResultContext {
+  readonly privateRuntime: PrivateRuntime;
+  readonly request: OmpSdkSidecarRequest;
+  readonly controller: AbortController;
+  readonly options: OmpSdkProcessRunnerOptions;
+  readonly collector: OmpSdkProtocolCollector;
+  readonly closePromise: Promise<ChildOutcome>;
+  readonly writePromise: Promise<void>;
+  readonly state: OmpSdkSupervisionState;
+  readonly secretValues: readonly string[];
+  readonly startedAt: number;
+  readonly externalAbort: () => void;
+}
+
+export async function collectOmpSdkProcessResult(
+  context: OmpSdkResultContext
+): Promise<OmpSdkProcessResult> {
+  const {
+    privateRuntime,
+    request,
+    controller,
+    options,
+    collector,
+    closePromise,
+    writePromise,
+    state,
+    secretValues,
+    startedAt,
+    externalAbort,
+  } = context;
+  let rootRemoved = false;
+  try {
+    await writePromise;
+    const outcome = await closePromise;
+    if (outcome.spawnError !== undefined) throw outcome.spawnError;
+
+    let supervisorAttestation;
+    try {
+      supervisorAttestation = parseOmpSdkSupervisorAttestation(
+        Buffer.concat(state.attestationChunks)
+      );
+    } catch (error) {
+      throw new OmpSdkProcessRunnerError(
+        'cleanup-error',
+        'OMP SDK supervisor cleanup attestation is malformed or unavailable.',
+        { cause: error }
+      );
+    }
+    if (supervisorAttestation.status === 'error') {
+      throw new OmpSdkProcessRunnerError(
+        supervisorAttestation.code === 'capability-unavailable'
+          ? 'containment-error'
+          : 'cleanup-error',
+        supervisorAttestation.code === 'capability-unavailable'
+          ? 'OMP SDK Linux subreaper/pidfd containment is unavailable.'
+          : 'OMP SDK supervisor could not attest descendant cleanup.'
+      );
+    }
+    if (outcome.exitCode !== 0 || outcome.signal !== null) {
+      throw new OmpSdkProcessRunnerError(
+        'cleanup-error',
+        'OMP SDK supervisor did not exit cleanly after its cleanup attestation.'
+      );
+    }
+    if (supervisorAttestation.cancelled !== controller.signal.aborted) {
+      throw new OmpSdkProcessRunnerError(
+        'cleanup-error',
+        'OMP SDK supervisor cancellation attestation does not match the owner state.'
+      );
+    }
+
+    let terminal: OmpSdkCollectedTerminal | undefined;
+    if (!controller.signal.aborted && state.protocolError === undefined) {
+      if (supervisorAttestation.semantic.exitCode === null) {
+        state.protocolError = new OmpSdkProcessRunnerError(
+          'protocol-error',
+          'OMP SDK sidecar terminated by signal without cancellation.'
+        );
+      } else {
+        try {
+          terminal = collector.finish(supervisorAttestation.semantic.exitCode);
+        } catch (error) {
+          state.protocolError = error;
+        }
+      }
+    }
+
+    await removePrivateRoot(privateRuntime);
+    rootRemoved = true;
+    const cleanupAttestation: OmpSdkCleanupAttestation = {
+      mode: 'host-process-tree',
+      terminalBuffered: true,
+      descendantsReaped: true,
+      clean: true,
+    };
+    const diagnosticStderr = redactDiagnostic(Buffer.concat(state.stderrChunks).toString('utf8'), [
+      ...secretValues,
+      request.prompt,
+      request.context,
+    ]);
+    if (controller.signal.aborted) {
+      return {
+        stdout: '',
+        stderr: diagnosticStderr,
+        diagnosticStderr,
+        exitCode: supervisorAttestation.semantic.exitCode,
+        signal: supervisorAttestation.semantic.signal,
+        durationMs: Date.now() - startedAt,
+        timedOut: state.timedOut,
+        ...(state.timedOut && options.timeoutMs !== undefined
+          ? { timeoutMs: options.timeoutMs }
+          : {}),
+        terminal: cancelledTerminal(request),
+        progress: [...collector.progress],
+        cleanupAttestation,
+      };
+    }
+    if (state.protocolError !== undefined) throw state.protocolError;
+    if (terminal === undefined) {
+      throw new OmpSdkProcessRunnerError(
+        'protocol-error',
+        'OMP SDK terminal frame is unavailable.'
+      );
+    }
+    return {
+      stdout: '',
+      stderr: diagnosticStderr,
+      diagnosticStderr,
+      exitCode: supervisorAttestation.semantic.exitCode,
+      signal: supervisorAttestation.semantic.signal,
+      durationMs: Date.now() - startedAt,
+      timedOut: false,
+      terminal,
+      progress: [...collector.progress],
+      cleanupAttestation,
+    };
+  } catch (error) {
+    if (!rootRemoved) {
+      try {
+        await removePrivateRoot(privateRuntime);
+      } catch (removeError) {
+        throw new OmpSdkProcessRunnerError(
+          'cleanup-error',
+          'OMP SDK private-root cleanup failed after supervisor shutdown.',
+          { cause: removeError }
+        );
+      }
+    }
+    throw error;
+  } finally {
+    clearTimeout(state.timeout);
+    options.signal?.removeEventListener('abort', externalAbort);
+    for (const chunk of state.stderrChunks) chunk.fill(0);
+    for (const chunk of state.attestationChunks) chunk.fill(0);
+  }
+}

package/src/agent-cli-provider/omp/sdk-process-runner.ts

@@ -0,0 +1,281 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { isAbsolute } from 'node:path';
+
+import {
+  OMP_SDK_MAX_STDOUT_BYTES,
+  createOmpSdkProtocolCollector,
+  decodeOmpSdkSidecarRequest,
+} from './sdk-protocol';
+import {
+  OMP_SDK_MAX_SUPERVISOR_ATTESTATION_BYTES,
+  resolveOmpSdkHostSupervisorPath,
+} from './sdk-runtime';
+import type { PreparedSingleAgentProviderCommand } from '../single-agent-runtime';
+import {
+  DEFAULT_REAP_TIMEOUT_MS,
+  DEFAULT_TERMINATION_GRACE_MS,
+  MAX_STDERR_BYTES,
+  childClose,
+  credentialWriter,
+  duration,
+  testIdentityCapArgument,
+  writeCredentials,
+} from './sdk-process-io';
+import { collectOmpSdkProcessResult, type OmpSdkSupervisionState } from './sdk-process-result';
+import {
+  OmpSdkProcessRunnerError,
+  assertHostContainment,
+  assertPrepared,
+  childEnvironment,
+  credentialPayload,
+  makePrivateRuntime,
+  removePrivateRoot,
+  type OmpSdkProcessResult,
+  type OmpSdkProcessRunnerOptions,
+  type OmpSdkRunningProcess,
+  type PrivateRuntime,
+} from './sdk-process-private-runtime';
+
+export { OmpSdkProcessRunnerError } from './sdk-process-private-runtime';
+export type {
+  OmpSdkProcessResult,
+  OmpSdkProcessRunnerOptions,
+  OmpSdkRunningProcess,
+} from './sdk-process-private-runtime';
+
+export async function spawnOmpSdkProcess(
+  prepared: PreparedSingleAgentProviderCommand,
+  options: OmpSdkProcessRunnerOptions = {}
+): Promise<OmpSdkRunningProcess> {
+  assertPrepared(prepared);
+  let runtime: PrivateRuntime | undefined;
+  try {
+    const privateRuntime = await makePrivateRuntime(prepared.privateArtifacts);
+    runtime = privateRuntime;
+    assertHostContainment(prepared.containmentRequirement);
+    const requestBytes = await fs.readFile(privateRuntime.requestPath);
+    const request = decodeOmpSdkSidecarRequest(requestBytes);
+    requestBytes.fill(0);
+    const environment = childEnvironment(prepared.environmentPolicy, privateRuntime);
+    const { payload, secretValues } = credentialPayload(prepared.credentialNames, process.env);
+    const requestProvider = request.modelSelector.slice(0, request.modelSelector.indexOf('/'));
+    const sidecarPath = prepared.commandSpec.args[0] ?? '';
+    if (
+      !isAbsolute(prepared.commandSpec.binary) ||
+      prepared.commandSpec.args.length !== 2 ||
+      !isAbsolute(sidecarPath) ||
+      prepared.commandSpec.args[1] !== privateRuntime.requestPath ||
+      prepared.commandSpec.cwd !== request.cwd ||
+      Object.keys(prepared.commandSpec.env).length !== 0 ||
+      prepared.semanticIdentity.requestedModelSelector !== request.modelSelector ||
+      prepared.semanticIdentity.reasoningEffort !== request.reasoningEffort ||
+      prepared.semanticIdentity.provider !== requestProvider
+    ) {
+      payload.fill(0);
+      throw new OmpSdkProcessRunnerError(
+        'protocol-error',
+        'OMP SDK command metadata does not match its authoritative private request.'
+      );
+    }
+
+    const supervisorPath = resolveOmpSdkHostSupervisorPath();
+    let supervisorStat;
+    try {
+      supervisorStat = await fs.lstat(supervisorPath);
+    } catch (error) {
+      payload.fill(0);
+      throw new OmpSdkProcessRunnerError(
+        'containment-error',
+        'Pinned OMP SDK host supervisor is unavailable.',
+        { cause: error }
+      );
+    }
+    if (!supervisorStat.isFile() || supervisorStat.isSymbolicLink()) {
+      payload.fill(0);
+      throw new OmpSdkProcessRunnerError(
+        'containment-error',
+        'Pinned OMP SDK host supervisor is unavailable.'
+      );
+    }
+    const terminationGraceMs = duration(options.timeoutKillGraceMs, DEFAULT_TERMINATION_GRACE_MS);
+    const reapTimeoutMs = duration(options.reapTimeoutMs, DEFAULT_REAP_TIMEOUT_MS);
+    const startedAt = Date.now();
+    const collector = createOmpSdkProtocolCollector({
+      request,
+      maxStdoutBytes: OMP_SDK_MAX_STDOUT_BYTES,
+    });
+    const child = spawn(
+      prepared.commandSpec.binary,
+      [
+        supervisorPath,
+        sidecarPath,
+        privateRuntime.requestPath,
+        String(terminationGraceMs),
+        String(reapTimeoutMs),
+        ...testIdentityCapArgument(),
+      ],
+      {
+        cwd: prepared.commandSpec.cwd,
+        detached: false,
+        env: environment,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      }
+    );
+    const closePromise = childClose(child);
+    const pid = child.pid;
+    if (pid === undefined || pid <= 1) {
+      payload.fill(0);
+      const outcome = await closePromise;
+      throw (
+        outcome.spawnError ??
+        new OmpSdkProcessRunnerError('containment-error', 'OMP SDK supervisor PID is unavailable.')
+      );
+    }
+
+    const controller = new AbortController();
+    const state: OmpSdkSupervisionState = {
+      timedOut: false,
+      protocolError: undefined,
+      stderrChunks: [],
+      attestationChunks: [],
+      timeout: undefined,
+    };
+    let stderrBytes = 0;
+    let attestationBytes = 0;
+    const terminate = (): void => {
+      try {
+        child.kill('SIGCONT');
+        child.kill('SIGTERM');
+      } catch {
+        // Close/attestation decides whether cleanup is authoritative.
+      }
+    };
+    const externalAbort = (): void => controller.abort();
+    controller.signal.addEventListener('abort', terminate, { once: true });
+    options.signal?.addEventListener('abort', externalAbort, { once: true });
+    if (options.signal?.aborted) controller.abort();
+    if (options.timeoutMs !== undefined) {
+      state.timeout = setTimeout(() => {
+        state.timedOut = true;
+        controller.abort();
+      }, options.timeoutMs);
+      state.timeout.unref();
+    }
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      attestationBytes += chunk.byteLength;
+      if (attestationBytes > OMP_SDK_MAX_SUPERVISOR_ATTESTATION_BYTES) {
+        state.protocolError = new OmpSdkProcessRunnerError(
+          'cleanup-error',
+          'OMP SDK supervisor attestation is oversized.'
+        );
+        terminate();
+      } else {
+        state.attestationChunks.push(chunk);
+      }
+    });
+    child.stdout?.on('error', () => {
+      state.protocolError = new OmpSdkProcessRunnerError(
+        'cleanup-error',
+        'OMP SDK supervisor attestation channel failed.'
+      );
+      terminate();
+    });
+    const protocolChannel = child.stdio[4];
+    if (
+      protocolChannel === undefined ||
+      protocolChannel === null ||
+      typeof protocolChannel.on !== 'function'
+    ) {
+      state.protocolError = new OmpSdkProcessRunnerError(
+        'protocol-error',
+        'OMP SDK sidecar protocol channel was not created.'
+      );
+      terminate();
+    } else {
+      protocolChannel.on('data', (chunk: Buffer) => {
+        if (state.protocolError !== undefined) return;
+        try {
+          for (const frame of collector.write(chunk)) {
+            if (frame.type === 'progress') options.onProgress?.(frame);
+          }
+        } catch (error) {
+          state.protocolError = error;
+          terminate();
+        }
+      });
+      protocolChannel.on('error', (error: Error) => {
+        state.protocolError = new OmpSdkProcessRunnerError(
+          'protocol-error',
+          'OMP SDK sidecar protocol channel failed.',
+          { cause: error }
+        );
+        terminate();
+      });
+    }
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderrBytes += chunk.byteLength;
+      if (stderrBytes > MAX_STDERR_BYTES) {
+        state.protocolError = new OmpSdkProcessRunnerError(
+          'protocol-error',
+          'OMP SDK diagnostic stderr is oversized.'
+        );
+        terminate();
+      } else {
+        state.stderrChunks.push(chunk);
+      }
+    });
+    child.stderr?.on('error', (error: Error) => {
+      state.protocolError = new OmpSdkProcessRunnerError(
+        'protocol-error',
+        'OMP SDK diagnostic channel failed.',
+        { cause: error }
+      );
+      terminate();
+    });
+
+    const writePromise = writeCredentials(credentialWriter(child), payload).catch((error) => {
+      state.protocolError = new OmpSdkProcessRunnerError(
+        'protocol-error',
+        'OMP SDK credential channel failed.',
+        { cause: error }
+      );
+      terminate();
+    });
+
+    const result = collectOmpSdkProcessResult({
+      privateRuntime,
+      request,
+      controller,
+      options,
+      collector,
+      closePromise,
+      writePromise,
+      state,
+      secretValues,
+      startedAt,
+      externalAbort,
+    });
+
+    return {
+      pid,
+      result,
+      cancel: () => controller.abort(),
+    };
+  } catch (error) {
+    if (runtime !== undefined) {
+      await removePrivateRoot(runtime);
+    }
+    throw error;
+  }
+}
+
+export async function runOmpSdkProcess(
+  prepared: PreparedSingleAgentProviderCommand,
+  options: OmpSdkProcessRunnerOptions = {}
+): Promise<OmpSdkProcessResult> {
+  return (await spawnOmpSdkProcess(prepared, options)).result;
+}