@omercnet/paseo-omp 0.4.0 → 1.0.0

package/scripts/prepare-dependencies.mjs

@@ -1,21 +1,54 @@
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 
-export function prepareDependencies(root = projectRoot, execute = execFileSync) {
-  if (!existsSync(join(root, "package-lock.json"))) return false;
+function loadRootCatalog(root) {
+  for (let directory = root; ; directory = dirname(directory)) {
+    const manifestPath = join(directory, "package.json");
+    if (existsSync(manifestPath)) {
+      const catalog = JSON.parse(readFileSync(manifestPath, "utf8")).catalog;
+      if (catalog) return catalog;
+    }
+    if (directory === dirname(directory)) return null;
+  }
+}
+
+function stageManifest(root, catalog, install) {
+  const manifestPath = join(root, "package.json");
+  const source = readFileSync(manifestPath, "utf8");
+  const manifest = JSON.parse(source);
+
+  for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
+    if (spec !== "catalog:") continue;
+    if (typeof catalog[name] !== "string") throw new Error(`Missing catalog entry for ${name}`);
+    manifest.dependencies[name] = catalog[name];
+  }
+  delete manifest.devDependencies;
 
-  execute(
-    process.platform === "win32" ? "npm.cmd" : "npm",
-    ["ci", "--omit=dev", "--ignore-scripts"],
-    {
-      cwd: root,
-      stdio: "inherit",
-    },
-  );
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  try {
+    install();
+  } finally {
+    writeFileSync(manifestPath, source);
+  }
+}
+
+export function prepareDependencies(root = projectRoot, execute = execFileSync) {
+  const catalog = loadRootCatalog(root);
+  if (!catalog) return false;
+  stageManifest(root, catalog, () => {
+    execute(
+      process.platform === "win32" ? "npm.cmd" : "npm",
+      ["install", "--omit=dev", "--ignore-scripts", "--no-package-lock", "--workspaces=false"],
+      {
+        cwd: root,
+        stdio: "inherit",
+      },
+    );
+  });
   return true;
 }
 

package/server/omp-models.ts

@@ -3,12 +3,8 @@ import { isAbsolute } from "node:path";
 import type { RpcInput } from "@getpaseo/plugin";
 import type { listOmpModels, OmpModelCandidate, OmpModelListResult } from "../shared/omp-models";
 import { currentOmpEnvironment } from "./paths";
-import {
-  type OmpModel,
-  OmpRpcRuntime,
-  type OmpRuntime,
-  type OmpRuntimeSession,
-} from "./provider/omp-rpc";
+import { OmpRpcRuntime, type OmpRuntime, type OmpRuntimeSession } from "./provider/omp-rpc";
+import type { OmpModel } from "./provider/omp-rpc-protocol";
 import { OmpCleanupFailure, OmpPublicDataSerializer, OmpPublicError } from "./provider/security";
 
 function mapOmpModel(model: OmpModel, serializer: OmpPublicDataSerializer): OmpModelCandidate {

package/server/package-version.ts

@@ -1,2 +1,2 @@
 /** Release Please keeps this bundle-safe constant aligned with package.json. */
-export const PASEO_OMP_PACKAGE_VERSION = "0.4.0"; // x-release-please-version
+export const PASEO_OMP_PACKAGE_VERSION = "1.0.0"; // x-release-please-version

package/server/protocol-violation-diagnostics.ts

@@ -4,7 +4,7 @@ import {
   type OmpProtocolViolationCategory,
   type OmpProtocolViolationDiagnostic,
   type OmpProtocolViolationReason,
-} from "./provider/omp-rpc";
+} from "./provider/omp-rpc-protocol";
 
 export interface OmpProtocolViolationSummary {
   category: OmpProtocolViolationCategory;

package/server/provider/catalog.ts

@@ -6,7 +6,8 @@ import type {
   ProviderThinkingOption,
 } from "@getpaseo/plugin/server/provider";
 import type { NormalizedOmpStartOptions } from "./config-normalization";
-import type { OmpModel, OmpRuntime, OmpRuntimeSession } from "./omp-rpc";
+import type { OmpRuntime, OmpRuntimeSession } from "./omp-rpc";
+import type { OmpModel } from "./omp-rpc-protocol";
 import {
   configuredOutputRedactionValues,
   OmpCleanupFailure,

package/server/provider/config-normalization.ts

@@ -1,5 +1,5 @@
 import type { ProviderSessionConfig } from "@getpaseo/plugin/server/provider";
-import type { OmpStartOptions } from "./omp-rpc";
+import type { OmpStartOptions } from "./omp-rpc-environment";
 
 type ProviderCatalogOptionsCompat = {
   scope: "global" | "workspace";
@@ -9,6 +9,7 @@ type ProviderCatalogOptionsCompat = {
   settings?: Readonly<Record<string, unknown>>;
 };
 
+import { MAX_INHERITED_ENVIRONMENT_NAMES } from "../../shared/provider-launch-settings";
 import { parseOmpProviderOptions } from "./provider-options";
 import { OmpPublicError } from "./security";
 import { OmpModeSchema } from "./settings";
@@ -59,11 +60,24 @@ function allowedOmpTools(deniedTools: readonly string[] | undefined): string[] |
 
 export type NormalizedOmpStartOptions = Omit<OmpStartOptions, "environment" | "signal">;
 export type OmpRecoveryOptions = Omit<OmpStartOptions, "resumeSessionId" | "signal">;
+export function mergeOmpInheritedEnvironmentNames(
+  hostNames: readonly string[],
+  profileNames: readonly string[] | undefined,
+): string[] | undefined {
+  const names = [...new Set([...hostNames, ...(profileNames ?? [])])];
+  if (names.length > MAX_INHERITED_ENVIRONMENT_NAMES) {
+    throw new OmpPublicError("OMP inherited environment has too many entries");
+  }
+  return names.length > 0 ? names : undefined;
+}
+
 export function normalizeOmpCatalogOptions(
   options: ProviderCatalogOptionsCompat,
   cwd: string,
+  hostInheritEnv: readonly string[] = [],
 ): Omit<OmpStartOptions, "environment" | "signal"> {
   const providerOptions = parseOmpProviderOptions(options.providerOptions);
+  const inheritEnv = mergeOmpInheritedEnvironmentNames(hostInheritEnv, providerOptions.inheritEnv);
   const params = providerOptions.params ?? {};
   return {
     cwd,
@@ -71,7 +85,7 @@ export function normalizeOmpCatalogOptions(
     noSession: true,
     ...(providerOptions.command ? { command: providerOptions.command } : {}),
     ...(providerOptions.env ? { env: providerOptions.env } : {}),
-    ...(providerOptions.inheritEnv ? { inheritEnv: providerOptions.inheritEnv } : {}),
+    ...(inheritEnv ? { inheritEnv } : {}),
     outputRedaction: providerOptions.outputRedaction,
     ...(params.sessionDir ? { sessionDir: params.sessionDir } : {}),
     ...(params.rpcTimeoutMs
@@ -103,6 +117,7 @@ export function withCommittedOmpSelection(
 export function normalizeOmpSessionConfig(
   config: ProviderSessionConfig,
   permissionSupported = false,
+  hostInheritEnv: readonly string[] = [],
 ): NormalizedOmpStartOptions {
   if (Object.keys(config.settings).length > 0) {
     throw new OmpPublicError("OMP does not expose live provider settings");
@@ -122,11 +137,12 @@ export function normalizeOmpSessionConfig(
   const tools = allowedOmpTools(deniedTools);
   const params = options.params ?? {};
   const env = { ...options.env, ...config.env };
+  const inheritEnv = mergeOmpInheritedEnvironmentNames(hostInheritEnv, options.inheritEnv);
   return {
     cwd: config.cwd,
     ...(options.command ? { command: options.command } : {}),
     ...(Object.keys(env).length > 0 ? { env } : {}),
-    ...(options.inheritEnv ? { inheritEnv: options.inheritEnv } : {}),
+    ...(inheritEnv ? { inheritEnv } : {}),
     outputRedaction: options.outputRedaction,
     mode: parsedMode.data,
     thinkingOption: config.thinkingOption,

package/server/provider/connection.ts

@@ -17,6 +17,13 @@ import { discoverOmpCatalog } from "./catalog";
 import { normalizeOmpCatalogOptions } from "./config-normalization";
 import type { OmpMcpConnector } from "./host-tools";
 import type { OmpRuntime } from "./omp-rpc";
+import {
+  OMP_RPC_BOUND_DIMENSIONS,
+  OMP_RPC_DIAGNOSTIC_COMMANDS,
+  type OmpRpcBoundDimension,
+  type OmpRpcDiagnosticCommand,
+} from "./omp-rpc-protocol";
+import { OmpRpcResponseLimitError } from "./omp-rpc-transport";
 import {
   boundedJsonBytes,
   isOmpCleanupFailure,
@@ -320,6 +327,10 @@ export interface OmpConnectionDiagnostic {
   code?: (typeof SYSTEM_ERROR_CODES)[number] | (typeof DATABASE_ERROR_CODES)[number];
   exitCode?: number;
   signal?: (typeof EXIT_SIGNALS)[number];
+  command?: OmpRpcDiagnosticCommand;
+  bound?: OmpRpcBoundDimension;
+  actual?: number;
+  limit?: number;
 }
 
 // Match complete, locally authored messages only. Never log an arbitrary message, error name,
@@ -428,6 +439,22 @@ function classifyFailure(
                 : "NonError",
     classification: "unexpected",
   };
+  if (error instanceof OmpRpcResponseLimitError) {
+    const command = OMP_RPC_DIAGNOSTIC_COMMANDS.find((value) => value === error.command);
+    const bound = OMP_RPC_BOUND_DIMENSIONS.find((value) => value === error.bound);
+    const actual =
+      Number.isSafeInteger(error.actual) && error.actual >= 0 ? error.actual : undefined;
+    const limit = Number.isSafeInteger(error.limit) && error.limit >= 0 ? error.limit : undefined;
+    return {
+      ...result,
+      classification: "rpc-response-limit",
+      stage: "rpc",
+      ...(command ? { command } : {}),
+      ...(bound ? { bound } : {}),
+      ...(actual !== undefined ? { actual } : {}),
+      ...(limit !== undefined ? { limit } : {}),
+    };
+  }
   const message = error instanceof Error ? error.message : undefined;
   if (typeof message === "string") {
     const known = KNOWN_FAILURES.get(message);
@@ -688,6 +715,7 @@ export function createOmpConnection(
   reportDiagnostic: (diagnostic: OmpConnectionDiagnostic) => void = (diagnostic) =>
     console.error("OMP provider failure", diagnostic),
   reportOperationalFailure: OmpOperationalFailureReporter = () => {},
+  resolveHostInheritEnv?: () => Promise<readonly string[]>,
 ): ProviderConnection {
   const errorDetails = (error: unknown, fallback: string): { message: string } => {
     if (isOmpPublicError(error)) return { message: error.message };
@@ -795,6 +823,7 @@ export function createOmpConnection(
               settings: configuredInput.settings,
             },
             input.cwd ?? homedir(),
+            (await resolveHostInheritEnv?.()) ?? [],
           );
           const catalog = await discoverOmpCatalog(
             runtime,
@@ -941,6 +970,7 @@ export function createOmpConnection(
             mcpConnector,
             mcpInitializationTimeoutMs,
             reportOperationalFailure,
+            (await resolveHostInheritEnv?.()) ?? [],
           );
           const discoveredNativeSessionId = session.persistenceSessionId;
           if (discoveredNativeSessionId) nativeSessionId = discoveredNativeSessionId;

package/server/provider/host-tools.ts

@@ -14,14 +14,14 @@ import {
   type ConnectedMcpToolPage,
   connectMcpServer,
 } from "./mcp-transport";
+import type { OmpRuntimeSession } from "./omp-rpc";
 import {
   OMP_HOST_TOOL_FRAME_LIMIT_ERROR,
   type OmpHostToolCall,
   type OmpHostToolDefinition,
   type OmpHostToolResult,
-  type OmpRuntimeSession,
   parseOmpHostToolAgentResult,
-} from "./omp-rpc";
+} from "./omp-rpc-protocol";
 import {
   boundedJsonBytes,
   OmpCleanupFailure,

package/server/provider/mcp-transport.ts

@@ -7,7 +7,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { deserializeMessage, serializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
 import type { FetchLike, Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-import { terminateSpawnedProcessTree } from "./omp-rpc";
+import { terminateSpawnedProcessTree } from "./omp-rpc-process";
 import { OmpCleanupFailure } from "./security";
 
 const MAX_MCP_TRANSPORT_FRAME_BYTES = 1024 * 1024;
@@ -225,7 +225,7 @@ export class SupervisedStdioClientTransport implements Transport {
       return;
     }
     const treeCleanup = this.startTreeCleanup();
-    if (!this.exited) {
+    if (this.platform !== "win32" && !this.exited) {
       try {
         child.stdin.end();
       } catch {
@@ -233,6 +233,13 @@ export class SupervisedStdioClientTransport implements Transport {
       }
     }
     const terminated = await treeCleanup;
+    if (this.platform === "win32" && terminated && !this.exited) {
+      try {
+        child.stdin.end();
+      } catch {
+        // Process-tree cleanup remains authoritative when the input channel is already closed.
+      }
+    }
     const exited =
       this.spawnFailedWithoutProcess ||
       this.exited ||

package/server/provider/omp-rpc-environment.ts

@@ -0,0 +1,368 @@
+import { isAbsolute } from "node:path";
+import {
+  MAX_MODEL_SELECTOR_BYTES,
+  MAX_PATH_LENGTH,
+  MAX_SYSTEM_PROMPT_LENGTH,
+  OmpThinkingLevelSchema,
+  validateBoundedText,
+} from "./omp-rpc-values";
+import { OmpPublicError, utf8Bytes } from "./security";
+import { validateNativeSessionId } from "./session-descriptors";
+import type { OmpOutputRedaction } from "./settings";
+
+const MAX_ENV_ENTRIES = 256;
+const MAX_ENV_VALUE_LENGTH = 64 * 1024;
+const MAX_ENV_TOTAL_LENGTH = 1024 * 1024;
+
+export interface OmpStartOptions {
+  cwd: string;
+  env?: Readonly<Record<string, string>>;
+  outputRedaction?: OmpOutputRedaction;
+  inheritEnv?: readonly string[];
+  /** Server-owned environment source; tests provide isolated roots instead of ambient process.env. */
+  environment?: NodeJS.ProcessEnv;
+  command?: readonly string[];
+  model?: string;
+  mode?: "full" | "write" | "ask";
+  thinkingOption?: string;
+  systemPrompt?: string;
+  roleModels?: Readonly<{ smol?: string; slow?: string; plan?: string }>;
+  tools?: readonly string[];
+  sessionDir?: string;
+  readyTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  /** Resume this exact native OMP session; never use this to start a new conversation. */
+  resumeSessionId?: string;
+  noSession?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface OmpSpawnRequest {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  detached: boolean;
+  inheritedRedactionValues: string[];
+}
+
+// The daemon contributes only process/runtime discovery variables plus provider authentication
+// families. Session-scoped values are explicit host input and are overlaid after rejecting loader
+// and executable-resolution controls; this keeps provider credentials available without copying
+const INHERITED_RUNTIME_ENV: Readonly<Record<string, true>> = {
+  ALL_PROXY: true,
+  APPDATA: true,
+  COLORTERM: true,
+  HOME: true,
+  HTTPS_PROXY: true,
+  HTTP_PROXY: true,
+  LANG: true,
+  LC_ALL: true,
+  LC_CTYPE: true,
+  LOCALAPPDATA: true,
+  LOGNAME: true,
+  NO_PROXY: true,
+  OMP_PROFILE: true,
+  PATH: true,
+  PATHEXT: true,
+  PI_CODING_AGENT_DIR: true,
+  PI_CONFIG_DIR: true,
+  PI_PROFILE: true,
+  SHELL: true,
+  SSH_AUTH_SOCK: true,
+  SSL_CERT_DIR: true,
+  SSL_CERT_FILE: true,
+  SYSTEMROOT: true,
+  TEMP: true,
+  TMP: true,
+  TMPDIR: true,
+  TZ: true,
+  USER: true,
+  USERPROFILE: true,
+  XDG_CACHE_HOME: true,
+  XDG_CONFIG_HOME: true,
+  XDG_DATA_HOME: true,
+  XDG_STATE_HOME: true,
+  XDG_RUNTIME_DIR: true,
+};
+const INHERITED_PROVIDER_AUTH_ENV: Readonly<Record<string, true>> = {
+  AI_GATEWAY_API_KEY: true,
+  AIAND_API_KEY: true,
+  ALIBABA_CODING_PLAN_API_KEY: true,
+  ALIBABA_TOKEN_PLAN_API_KEY: true,
+  ANTHROPIC_API_KEY: true,
+  ANTHROPIC_FOUNDRY_API_KEY: true,
+  ANTHROPIC_OAUTH_TOKEN: true,
+  AWS_ACCESS_KEY_ID: true,
+  AWS_DEFAULT_REGION: true,
+  AWS_PROFILE: true,
+  AWS_REGION: true,
+  AWS_SECRET_ACCESS_KEY: true,
+  AWS_SESSION_TOKEN: true,
+  AZURE_CLIENT_ID: true,
+  AZURE_CLIENT_SECRET: true,
+  AZURE_OPENAI_API_KEY: true,
+  AZURE_OPENAI_ENDPOINT: true,
+  AZURE_TENANT_ID: true,
+  BAILIAN_TOKEN_PLAN_API_KEY: true,
+  BASETEN_API_KEY: true,
+  CEREBRAS_API_KEY: true,
+  CHARM_HYPER_API_KEY: true,
+  CLINE_API_KEY: true,
+  CLOUDFLARE_AI_GATEWAY_API_KEY: true,
+  COHERE_API_KEY: true,
+  COMMAND_CODE_API_KEY: true,
+  COREWEAVE_API_KEY: true,
+  CURSOR_ACCESS_TOKEN: true,
+  DEEPINFRA_API_KEY: true,
+  DEEPSEEK_API_KEY: true,
+  DEVIN_API_KEY: true,
+  FIREPASS_API_KEY: true,
+  FIREWORKS_API_KEY: true,
+  FUGU_API_KEY: true,
+  GEMINI_API_KEY: true,
+  GMI_API_KEY: true,
+  GOOGLE_API_KEY: true,
+  GOOGLE_APPLICATION_CREDENTIALS: true,
+  GROQ_API_KEY: true,
+  HF_TOKEN: true,
+  HUGGINGFACE_HUB_TOKEN: true,
+  LLAMA_CPP_API_KEY: true,
+  LM_STUDIO_API_KEY: true,
+  META_API_KEY: true,
+  MINIMAX_API_KEY: true,
+  MINIMAX_CODE_API_KEY: true,
+  MINIMAX_CODE_CN_API_KEY: true,
+  MISTRAL_API_KEY: true,
+  MODEL_API_KEY: true,
+  MOONSHOT_API_KEY: true,
+  NANO_GPT_API_KEY: true,
+  NVIDIA_API_KEY: true,
+  NOVITA_API_KEY: true,
+  OLLAMA_API_KEY: true,
+  OLLAMA_CLOUD_API_KEY: true,
+  OLLAMA_HOST: true,
+  OMP_AUTH_BROKER_TOKEN: true,
+  OMP_AUTH_BROKER_URL: true,
+  OPENCODE_API_KEY: true,
+  OPENAI_API_KEY: true,
+  OPENAI_CODEX_OAUTH_TOKEN: true,
+  OPENROUTER_API_KEY: true,
+  PLEXUS_API_KEY: true,
+  QIANFAN_API_KEY: true,
+  QWEN_OAUTH_TOKEN: true,
+  QWEN_PORTAL_API_KEY: true,
+  SAKANA_API_KEY: true,
+  SILICONFLOW_API_KEY: true,
+  SILICONFLOW_CN_API_KEY: true,
+  SYNTHETIC_API_KEY: true,
+  TOGETHER_API_KEY: true,
+  UMANS_AI_CODING_PLAN_API_KEY: true,
+  VENICE_API_KEY: true,
+  VLLM_API_KEY: true,
+  WAFER_SERVERLESS_API_KEY: true,
+  WANDB_API_KEY: true,
+  XAI_API_KEY: true,
+  XAI_OAUTH_TOKEN: true,
+  XIAOMI_API_KEY: true,
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY: true,
+  XIAOMI_TOKEN_PLAN_CN_API_KEY: true,
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY: true,
+  YOLO_AUTO_API_KEY: true,
+  ZAI_API_KEY: true,
+  ZENMUX_API_KEY: true,
+  ZHIPU_API_KEY: true,
+};
+const BLOCKED_SESSION_ENV =
+  /^(?:BASH_ENV|BUN_INSTALL.*|BUN_OPTIONS|CLASSPATH|CLAUDE_BASH_NO_CI|CLAUDE_BASH_NO_LOGIN|CLAUDE_CODE_SHELL_PREFIX|DYLD_.*|EDITOR|ELECTRON_RUN_AS_NODE|ENV|GEM_HOME|GEM_PATH|GIT_CONFIG.*|GIT_SSH_COMMAND|HOME|JAVA_TOOL_OPTIONS|LD_.*|NODE_OPTIONS|NODE_PATH|NPM_CONFIG_.*|OMP_AUTORESEARCH_DB_DIR|OMP_COMMAND|OMP_GITHUB_CACHE_DB|OMP_PROFILE|OMP_WORKTREE_DIR|PATH|PATHEXT|PERL5LIB|PERL5OPT|PI_BASH_NO_CI|PI_BASH_NO_LOGIN|PI_CODING_AGENT_DIR|PI_CODING_AGENT_SESSION_DIR|PI_CONFIG_DIR|PI_CONFIG_FILES|PI_GIT_COMMON_DIR|PI_PACKAGE_DIR|PI_PROFILE|PI_PROJECT_DIR|PI_SESSION_ID|PI_SHELL_PREFIX|PI_SUBPROCESS_CMD|PI_WORKTREE_DIR|PWD|PYTHONHOME|PYTHONINSPECT|PYTHONPATH|PYTHONSTARTUP|RUBYLIB|RUBYOPT|SHELL|SYSTEMROOT|USERPROFILE|VISUAL|XDG_CACHE_HOME|XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_RUNTIME_DIR|XDG_STATE_HOME|_JAVA_OPTIONS)$/u;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+
+function inheritedEnvironmentNames(inheritEnv: readonly string[] | undefined): ReadonlySet<string> {
+  if (inheritEnv === undefined) return new Set();
+  if (!Array.isArray(inheritEnv)) {
+    throw new Error("OMP inherited environment names are invalid");
+  }
+  if (inheritEnv.length > MAX_ENV_ENTRIES) {
+    throw new Error("OMP inherited environment has too many entries");
+  }
+  const names = new Set<string>();
+  for (const name of inheritEnv) {
+    if (typeof name !== "string" || !ENV_NAME.test(name)) {
+      throw new Error("OMP inherited environment contains an invalid name");
+    }
+    if (BLOCKED_SESSION_ENV.test(name.toUpperCase())) {
+      throw new Error("OMP inherited environment contains a forbidden variable");
+    }
+    names.add(name);
+  }
+  return names;
+}
+
+function buildOmpEnvironment(
+  sessionEnv: Readonly<Record<string, string>> | undefined,
+  inheritEnv: readonly string[] | undefined,
+  sourceEnv: NodeJS.ProcessEnv,
+): { env: NodeJS.ProcessEnv; inheritedRedactionValues: string[] } {
+  if (
+    sessionEnv !== undefined &&
+    (sessionEnv === null || typeof sessionEnv !== "object" || Array.isArray(sessionEnv))
+  ) {
+    throw new Error("OMP session environment is invalid");
+  }
+  const explicitlyInherited = inheritedEnvironmentNames(inheritEnv);
+  const explicitlyInheritedNormalized = new Set(
+    [...explicitlyInherited].map((name) => name.toUpperCase()),
+  );
+  const explicitNames = new Set(Object.keys(sessionEnv ?? {}).map((name) => name.toUpperCase()));
+  const env: NodeJS.ProcessEnv = {};
+  const inheritedRedactionValues: string[] = [];
+  let totalBytes = 0;
+  for (const [name, value] of Object.entries(sourceEnv)) {
+    if (value === undefined || name.toUpperCase() === "OMP_COMMAND") continue;
+    const normalizedName = name.toUpperCase();
+    const isRuntime =
+      process.platform === "win32"
+        ? normalizedName in INHERITED_RUNTIME_ENV
+        : name in INHERITED_RUNTIME_ENV;
+    const isProviderAuth =
+      process.platform === "win32"
+        ? normalizedName in INHERITED_PROVIDER_AUTH_ENV
+        : name in INHERITED_PROVIDER_AUTH_ENV;
+    const isExplicitlyInherited =
+      process.platform === "win32"
+        ? explicitlyInheritedNormalized.has(normalizedName)
+        : explicitlyInherited.has(name);
+    if (!isRuntime && !isProviderAuth && !isExplicitlyInherited) continue;
+    if (explicitNames.has(normalizedName)) continue;
+    const valueBytes = utf8Bytes(value);
+    if (!ENV_NAME.test(name) || valueBytes > MAX_ENV_VALUE_LENGTH || value.includes("\0")) {
+      if (isExplicitlyInherited) {
+        throw new Error("OMP inherited environment contains an invalid value");
+      }
+      continue;
+    }
+    if (isExplicitlyInherited && valueBytes > 0 && valueBytes < 4) {
+      throw new OmpPublicError("OMP inherited environment value is too short for safe redaction");
+    }
+    totalBytes += utf8Bytes(name) + valueBytes;
+    if (totalBytes > MAX_ENV_TOTAL_LENGTH) {
+      throw new Error("OMP inherited environment is too large");
+    }
+    env[name] = value;
+    if (isExplicitlyInherited && valueBytes > 0) inheritedRedactionValues.push(value);
+  }
+  let entryCount = 0;
+  for (const name in sessionEnv ?? {}) {
+    if (!Object.hasOwn(sessionEnv ?? {}, name)) continue;
+    entryCount += 1;
+    if (entryCount > MAX_ENV_ENTRIES)
+      throw new Error("OMP session environment has too many entries");
+    const value = (sessionEnv as Readonly<Record<string, string>>)[name];
+    const normalizedName = name.toUpperCase();
+    if (!ENV_NAME.test(name) || BLOCKED_SESSION_ENV.test(normalizedName)) {
+      throw new Error("OMP session environment contains a forbidden variable");
+    }
+    if (
+      typeof value !== "string" ||
+      utf8Bytes(value) > MAX_ENV_VALUE_LENGTH ||
+      value.includes("\0")
+    ) {
+      throw new Error("OMP session environment contains an invalid value");
+    }
+    const valueBytes = utf8Bytes(value);
+    totalBytes += utf8Bytes(name) + valueBytes;
+    if (totalBytes > MAX_ENV_TOTAL_LENGTH) throw new Error("OMP session environment is too large");
+    for (const inheritedName of Object.keys(env)) {
+      if (inheritedName !== name && inheritedName.toUpperCase() === normalizedName) {
+        delete env[inheritedName];
+      }
+    }
+    env[name] = value;
+  }
+  return { env, inheritedRedactionValues };
+}
+
+export function buildOmpSpawnRequest(
+  options: OmpStartOptions,
+  sourceEnv: NodeJS.ProcessEnv = process.env,
+): OmpSpawnRequest {
+  const environmentSource = options.environment ?? sourceEnv;
+  const cwd = validateBoundedText(options.cwd, "working directory", MAX_PATH_LENGTH);
+  if (!isAbsolute(cwd)) throw new Error("OMP working directory must be absolute");
+  const commandPrefix = options.command ?? [environmentSource.OMP_COMMAND ?? "omp"];
+  if (commandPrefix.length === 0) throw new Error("Invalid OMP command");
+  const [rawCommand, ...rawPrefixArgs] = commandPrefix;
+  const command = validateBoundedText(rawCommand, "command", MAX_PATH_LENGTH);
+  const args = rawPrefixArgs.map((argument) =>
+    validateBoundedText(argument, "command argument", MAX_PATH_LENGTH),
+  );
+  if (/[\r\n]/u.test(command)) throw new Error("Invalid OMP command");
+  const mode = options.mode ?? "full";
+  if (mode !== "full" && mode !== "write" && mode !== "ask") throw new Error("Invalid OMP mode");
+  const approvalMode = mode === "full" ? "yolo" : mode === "write" ? "write" : "always-ask";
+  if (!args.some((argument) => argument === "--mode" || argument.startsWith("--mode="))) {
+    args.push("--mode", "rpc-ui");
+  }
+  args.push("--approval-mode", approvalMode);
+  if (options.tools) {
+    if (options.tools.length === 0) args.push("--no-tools");
+    else args.push("--tools", options.tools.join(","));
+  }
+  if (options.model !== undefined) {
+    args.push("--model", validateBoundedText(options.model, "model", MAX_MODEL_SELECTOR_BYTES));
+  }
+  if (options.thinkingOption !== undefined) {
+    const thinking = OmpThinkingLevelSchema.safeParse(options.thinkingOption);
+    if (!thinking.success) throw new Error("Invalid OMP thinking option");
+    args.push("--thinking", thinking.data);
+  }
+  if (options.roleModels?.smol) {
+    args.push(
+      "--smol",
+      validateBoundedText(options.roleModels.smol, "smol model", MAX_MODEL_SELECTOR_BYTES),
+    );
+  }
+  if (options.roleModels?.slow) {
+    args.push(
+      "--slow",
+      validateBoundedText(options.roleModels.slow, "slow model", MAX_MODEL_SELECTOR_BYTES),
+    );
+  }
+  if (options.roleModels?.plan) {
+    args.push(
+      "--plan",
+      validateBoundedText(options.roleModels.plan, "plan model", MAX_MODEL_SELECTOR_BYTES),
+    );
+  }
+  if (options.sessionDir !== undefined) {
+    args.push(
+      "--session-dir",
+      validateBoundedText(options.sessionDir, "session directory", MAX_PATH_LENGTH),
+    );
+  }
+  if (options.resumeSessionId !== undefined) {
+    args.push("--resume", validateNativeSessionId(options.resumeSessionId));
+  }
+  if (options.noSession) args.push("--no-session");
+  const systemPrompt = options.systemPrompt?.trim();
+  if (systemPrompt) {
+    args.push(
+      "--append-system-prompt",
+      validateBoundedText(systemPrompt, "system prompt", MAX_SYSTEM_PROMPT_LENGTH),
+    );
+  }
+  const { env, inheritedRedactionValues } = buildOmpEnvironment(
+    options.env,
+    options.inheritEnv,
+    environmentSource,
+  );
+  env.OMP_NO_WEBP = "1";
+  return {
+    command,
+    args,
+    cwd,
+    env,
+    inheritedRedactionValues,
+    detached: process.platform !== "win32",
+  };
+}