@the-open-engine/zeroshot 6.30.1 → 6.31.0

package/src/agent-cli-provider/omp/sdk-settings-normalize.ts

@@ -0,0 +1,242 @@
+import { invalidField } from '../contract-errors';
+import { isRecord } from '../json';
+import { EFFORTS, LEVELS, TOP_LEVEL_FIELDS } from './sdk-settings-constants';
+import { normalizeAuth } from './sdk-settings-auth';
+import { normalizeModelsConfig, validateSelectedProviderAuth } from './sdk-settings-model';
+import { parseExactOmpModelSelector } from './sdk-settings-selector';
+import {
+  OMP_SDK_TOOL_IDS,
+  type ConfiguredOmpSdkSettings,
+  type OmpLevelOverride,
+  type OmpModelLevel,
+  type OmpModelsConfig,
+  type OmpSdkSettings,
+  type OmpSdkToolId,
+  type OmpSettingsValidationContext,
+} from './sdk-settings-types';
+import {
+  deepFreeze,
+  enumValue,
+  falseOnly,
+  levelValue,
+  rejectUnknown,
+  stableValue,
+} from './sdk-settings-values';
+
+export const OMP_SDK_SETTINGS_DEFAULTS: Readonly<OmpSdkSettings> = deepFreeze<OmpSdkSettings>({
+  transport: 'sdk',
+  minLevel: 'level1',
+  defaultLevel: 'level2',
+  maxLevel: 'level3',
+  levelOverrides: {},
+  modelsConfig: { providers: {} },
+  tools: [...OMP_SDK_TOOL_IDS],
+  nestedAgents: false,
+  mcp: false,
+});
+
+class OmpSdkSettingsFunctions {
+  static normalizeOmpSdkSettings(
+    input: unknown,
+    context: OmpSettingsValidationContext & { readonly requireModelConfiguration: true }
+  ): Readonly<ConfiguredOmpSdkSettings>;
+  static normalizeOmpSdkSettings(
+    input: unknown,
+    context?: OmpSettingsValidationContext
+  ): Readonly<OmpSdkSettings>;
+  static normalizeOmpSdkSettings(
+    input: unknown,
+    context: OmpSettingsValidationContext = {}
+  ): Readonly<OmpSdkSettings> {
+    if (!isRecord(input)) {
+      invalidField('providerSettings.omp', 'providerSettings.omp must be an object.');
+    }
+    rejectUnknown(input, TOP_LEVEL_FIELDS, 'providerSettings.omp');
+
+    const transport = enumValue(
+      input.transport ?? OMP_SDK_SETTINGS_DEFAULTS.transport,
+      ['sdk', 'rpc'] as const,
+      'providerSettings.omp.transport'
+    );
+    const minLevel = levelValue(
+      input.minLevel ?? OMP_SDK_SETTINGS_DEFAULTS.minLevel,
+      'providerSettings.omp.minLevel'
+    );
+    const defaultLevel = levelValue(
+      input.defaultLevel ?? OMP_SDK_SETTINGS_DEFAULTS.defaultLevel,
+      'providerSettings.omp.defaultLevel'
+    );
+    const maxLevel = levelValue(
+      input.maxLevel ?? OMP_SDK_SETTINGS_DEFAULTS.maxLevel,
+      'providerSettings.omp.maxLevel'
+    );
+    if (
+      LEVELS.indexOf(minLevel) > LEVELS.indexOf(defaultLevel) ||
+      LEVELS.indexOf(defaultLevel) > LEVELS.indexOf(maxLevel)
+    ) {
+      invalidField(
+        'providerSettings.omp.defaultLevel',
+        'OMP level bounds must satisfy minLevel <= defaultLevel <= maxLevel.'
+      );
+    }
+
+    const levelOverrides = normalizeLevelOverrides(
+      input.levelOverrides ?? OMP_SDK_SETTINGS_DEFAULTS.levelOverrides
+    );
+    const configuredLevelOverrides = hasAllLevelOverrides(levelOverrides)
+      ? levelOverrides
+      : undefined;
+    const hasModelConfiguration = configuredLevelOverrides !== undefined;
+    if (context.requireModelConfiguration === true && !hasModelConfiguration) {
+      invalidField(
+        'providerSettings.omp.levelOverrides',
+        'OMP execution requires explicit full provider/model selectors for every level.'
+      );
+    }
+    const auth = input.auth === undefined ? undefined : normalizeAuth(input.auth, context);
+    if (hasModelConfiguration && auth === undefined) {
+      invalidField(
+        'providerSettings.omp.auth',
+        'Configured OMP models require an explicit authentication mode.'
+      );
+    }
+    const modelsConfig = normalizeModelsConfig(
+      input.modelsConfig ?? OMP_SDK_SETTINGS_DEFAULTS.modelsConfig,
+      auth
+    );
+    if (configuredLevelOverrides !== undefined && auth !== undefined) {
+      validateSelectedProviderAuth(configuredLevelOverrides, modelsConfig, auth);
+    }
+
+    const tools = normalizeTools(input.tools ?? OMP_SDK_SETTINGS_DEFAULTS.tools);
+    const nestedAgents = falseOnly(
+      input.nestedAgents ?? OMP_SDK_SETTINGS_DEFAULTS.nestedAgents,
+      'providerSettings.omp.nestedAgents'
+    );
+    const mcp = falseOnly(input.mcp ?? OMP_SDK_SETTINGS_DEFAULTS.mcp, 'providerSettings.omp.mcp');
+
+    return deepFreeze({
+      transport,
+      minLevel,
+      defaultLevel,
+      maxLevel,
+      levelOverrides,
+      modelsConfig,
+      ...(auth === undefined ? {} : { auth }),
+      tools,
+      nestedAgents,
+      mcp,
+    });
+  }
+
+  static resolveOmpSdkSettings(
+    settings: unknown,
+    context: OmpSettingsValidationContext & { readonly requireModelConfiguration: true }
+  ): Readonly<ConfiguredOmpSdkSettings>;
+  static resolveOmpSdkSettings(
+    settings: unknown,
+    context?: OmpSettingsValidationContext
+  ): Readonly<OmpSdkSettings>;
+  static resolveOmpSdkSettings(
+    settings: unknown,
+    context: OmpSettingsValidationContext = {}
+  ): Readonly<OmpSdkSettings> {
+    if (!isRecord(settings)) {
+      invalidField('settings', 'Zeroshot settings must be an object.');
+    }
+    const providerSettings = settings.providerSettings;
+    if (providerSettings !== undefined && !isRecord(providerSettings)) {
+      invalidField('providerSettings', 'providerSettings must be an object.');
+    }
+    const omp = providerSettings?.omp;
+    return OmpSdkSettingsFunctions.normalizeOmpSdkSettings(omp === undefined ? {} : omp, context);
+  }
+}
+
+export const normalizeOmpSdkSettings = OmpSdkSettingsFunctions.normalizeOmpSdkSettings;
+export const resolveOmpSdkSettings = OmpSdkSettingsFunctions.resolveOmpSdkSettings;
+
+export function validateOmpSdkSettings(
+  settings: Record<string, unknown>,
+  context: OmpSettingsValidationContext = {}
+): string | null {
+  try {
+    normalizeOmpSdkSettings(settings, context);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : 'Invalid providerSettings.omp configuration.';
+  }
+}
+
+export function compilePrivateOmpModelsYaml(
+  input: Readonly<OmpSdkSettings> | OmpModelsConfig
+): string {
+  const modelsConfig =
+    'modelsConfig' in input
+      ? normalizeOmpSdkSettings(input).modelsConfig
+      : normalizeModelsConfig(input);
+  return `${JSON.stringify(stableValue({ providers: modelsConfig.providers }), null, 2)}\n`;
+}
+
+function hasAllLevelOverrides(
+  value: Readonly<Partial<Record<OmpModelLevel, OmpLevelOverride>>>
+): value is Readonly<Record<OmpModelLevel, OmpLevelOverride>> {
+  return LEVELS.every((level) => value[level] !== undefined);
+}
+
+function normalizeLevelOverrides(value: unknown): Partial<Record<OmpModelLevel, OmpLevelOverride>> {
+  if (!isRecord(value)) {
+    invalidField('providerSettings.omp.levelOverrides', 'OMP levelOverrides must be an object.');
+  }
+  rejectUnknown(value, new Set(LEVELS), 'providerSettings.omp.levelOverrides');
+  if (Object.keys(value).length === 0) return {};
+  const result: Partial<Record<OmpModelLevel, OmpLevelOverride>> = {};
+  for (const level of LEVELS) {
+    const override = value[level];
+    const field = `providerSettings.omp.levelOverrides.${level}`;
+    if (!isRecord(override)) {
+      invalidField(field, `${field} is required and must be an object.`);
+    }
+    rejectUnknown(override, new Set(['model', 'reasoningEffort']), field);
+    if (!Object.prototype.hasOwnProperty.call(override, 'model')) {
+      invalidField(`${field}.model`, `${field}.model is required.`);
+    }
+    const selector = parseExactOmpModelSelector(override.model);
+    const reasoningEffort = enumValue(
+      override.reasoningEffort,
+      EFFORTS,
+      `${field}.reasoningEffort`
+    );
+    result[level] = { model: `${selector.provider}/${selector.model}`, reasoningEffort };
+  }
+  return result;
+}
+
+function normalizeTools(value: unknown): OmpSdkToolId[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    invalidField('providerSettings.omp.tools', 'OMP tools must be a non-empty allowlist.');
+  }
+  const result: OmpSdkToolId[] = [];
+  const seen = new Set<string>();
+  for (const [index, item] of value.entries()) {
+    if (!isOmpSdkToolId(item)) {
+      invalidField(
+        `providerSettings.omp.tools[${index}]`,
+        `OMP tools are restricted to: ${OMP_SDK_TOOL_IDS.join(', ')}.`
+      );
+    }
+    if (seen.has(item)) {
+      invalidField(
+        `providerSettings.omp.tools[${index}]`,
+        'OMP tool allowlists cannot contain duplicates.'
+      );
+    }
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+function isOmpSdkToolId(value: unknown): value is OmpSdkToolId {
+  return typeof value === 'string' && OMP_SDK_TOOL_IDS.some((candidate) => candidate === value);
+}

package/src/agent-cli-provider/omp/sdk-settings-selector.ts

@@ -0,0 +1,28 @@
+import { invalidField } from '../contract-errors';
+import { MODEL_COMPONENT, PROVIDER_ID } from './sdk-settings-constants';
+import type { ExactOmpModelSelector } from './sdk-settings-types';
+
+export function parseExactOmpModelSelector(selector: unknown): ExactOmpModelSelector {
+  if (typeof selector !== 'string' || selector.length === 0 || selector !== selector.trim()) {
+    invalidField(
+      'modelSelector',
+      'OMP model selectors must be non-empty strings without surrounding whitespace.'
+    );
+  }
+  const separator = selector.indexOf('/');
+  const provider = separator === -1 ? '' : selector.slice(0, separator);
+  const model = separator === -1 ? '' : selector.slice(separator + 1);
+  if (
+    !PROVIDER_ID.test(provider) ||
+    !MODEL_COMPONENT.test(model) ||
+    model.length === 0 ||
+    model.includes(',') ||
+    model.startsWith('@')
+  ) {
+    invalidField(
+      'modelSelector',
+      'OMP model selectors must be exact full provider/model selectors with no fallback chain or alias.'
+    );
+  }
+  return { provider, model };
+}

package/src/agent-cli-provider/omp/sdk-settings-types.ts

@@ -0,0 +1,88 @@
+export const OMP_SDK_TOOL_IDS = [
+  'read',
+  'bash',
+  'edit',
+  'write',
+  'grep',
+  'glob',
+  'lsp',
+  'ast_edit',
+] as const;
+export const OMP_SDK_REASONING_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'] as const;
+export const OMP_AUTH_BROKER_ENV_NAMES = Object.freeze({
+  url: 'OMP_AUTH_BROKER_URL',
+  token: 'OMP_AUTH_BROKER_TOKEN',
+});
+
+export type OmpSdkToolId = (typeof OMP_SDK_TOOL_IDS)[number];
+export type OmpTransport = 'sdk' | 'rpc';
+export type OmpModelLevel = 'level1' | 'level2' | 'level3';
+export type OmpReasoningEffort = (typeof OMP_SDK_REASONING_EFFORTS)[number];
+export type OmpExecutionContext = 'host' | 'detached' | 'docker';
+
+export interface ExactOmpModelSelector {
+  readonly provider: string;
+  readonly model: string;
+}
+
+export interface OmpLevelOverride {
+  readonly model: string;
+  readonly reasoningEffort: OmpReasoningEffort;
+}
+
+export interface OmpEnvironmentAuth {
+  readonly mode: 'environment';
+  readonly credentials: Readonly<Record<string, { readonly env: string }>>;
+}
+
+export interface OmpBrokerAuth {
+  readonly mode: 'broker';
+}
+
+export interface OmpHomeAuth {
+  readonly mode: 'omp-home';
+  /** Explicit OMP agent/config directory containing agent.db, not a HOME root. */
+  readonly path: string;
+}
+
+export interface OmpNoneAuth {
+  readonly mode: 'none';
+}
+
+export type OmpSdkAuth = OmpEnvironmentAuth | OmpBrokerAuth | OmpHomeAuth | OmpNoneAuth;
+
+export interface OmpModelDefinition {
+  readonly [field: string]: unknown;
+  readonly id: string;
+}
+
+export interface OmpProviderConfig {
+  readonly [field: string]: unknown;
+}
+
+export interface OmpModelsConfig {
+  readonly providers: Readonly<Record<string, OmpProviderConfig>>;
+}
+
+export interface OmpSdkSettings {
+  readonly transport: OmpTransport;
+  readonly minLevel: OmpModelLevel;
+  readonly defaultLevel: OmpModelLevel;
+  readonly maxLevel: OmpModelLevel;
+  readonly levelOverrides: Readonly<Partial<Record<OmpModelLevel, OmpLevelOverride>>>;
+  readonly modelsConfig: OmpModelsConfig;
+  readonly auth?: OmpSdkAuth;
+  readonly tools: readonly OmpSdkToolId[];
+  readonly nestedAgents: false;
+  readonly mcp: false;
+}
+
+export interface ConfiguredOmpSdkSettings extends OmpSdkSettings {
+  readonly levelOverrides: Readonly<Record<OmpModelLevel, OmpLevelOverride>>;
+  readonly auth: OmpSdkAuth;
+}
+
+export interface OmpSettingsValidationContext {
+  readonly executionContext?: OmpExecutionContext;
+  readonly requireModelConfiguration?: boolean;
+}

package/src/agent-cli-provider/omp/sdk-settings-values.ts

@@ -0,0 +1,118 @@
+import { invalidField } from '../contract-errors';
+import { isRecord } from '../json';
+import { LEVELS, PROVIDER_ID } from './sdk-settings-constants';
+import type { OmpModelLevel } from './sdk-settings-types';
+
+export function safeUrl(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.length === 0 || value !== value.trim()) {
+    invalidField(field, `${field} must be a non-empty URL.`);
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    invalidField(field, `${field} must be an absolute URL.`);
+  }
+  if (parsed.username || parsed.password) {
+    invalidField(field, `${field} must not contain URL userinfo.`);
+  }
+  if (parsed.search || parsed.hash) {
+    invalidField(field, `${field} must not contain query parameters or fragments.`);
+  }
+  const loopback =
+    parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '::1';
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+    invalidField(field, `${field} must use HTTPS, except for loopback HTTP providers.`);
+  }
+  return parsed.toString().replace(/\/$/, '');
+}
+
+export function emptyHeaders(value: unknown, field: string): Record<string, never> {
+  if (!isRecord(value)) invalidField(field, `${field} must be an object.`);
+  if (Object.keys(value).length !== 0) {
+    invalidField(field, 'Literal custom headers may persist credentials and are not accepted.');
+  }
+  return {};
+}
+
+export function rejectUnknown(
+  value: Record<string, unknown>,
+  allowed: ReadonlySet<string>,
+  field: string
+): void {
+  const unknown = Object.keys(value).find((key) => !allowed.has(key));
+  if (unknown !== undefined) {
+    invalidField(`${field}.${unknown}`, `Unknown OMP setting: ${field}.${unknown}.`);
+  }
+}
+
+export function levelValue(value: unknown, field: string): OmpModelLevel {
+  return enumValue(value, LEVELS, field);
+}
+
+export function enumValue<const T extends readonly string[]>(
+  value: unknown,
+  allowed: T,
+  field: string
+): T[number] {
+  if (typeof value === 'string' && (allowed as readonly string[]).includes(value)) {
+    return value as T[number];
+  }
+  invalidField(field, `${field} must be one of: ${allowed.join(', ')}.`);
+}
+
+export function falseOnly(value: unknown, field: string): false {
+  if (value === false) return false;
+  invalidField(field, `${field} must be false.`);
+}
+
+export function booleanValue(value: unknown, field: string): boolean {
+  if (typeof value === 'boolean') return value;
+  invalidField(field, `${field} must be a boolean.`);
+}
+
+export function nonEmptyString(value: unknown, field: string): string {
+  if (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value === value.trim() &&
+    !value.includes('\0')
+  ) {
+    return value;
+  }
+  invalidField(field, `${field} must be a non-empty string without surrounding whitespace.`);
+}
+
+export function nonNegativeNumber(value: unknown, field: string): number {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
+  invalidField(field, `${field} must be a finite non-negative number.`);
+}
+
+export function assertProviderId(provider: string, field: string): void {
+  if (!PROVIDER_ID.test(provider)) {
+    invalidField(
+      field,
+      'OMP provider IDs must use lowercase letters, numbers, dots, underscores, or hyphens.'
+    );
+  }
+}
+
+export function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort((left, right) => left.localeCompare(right))
+      .map((key) => [key, stableValue(value[key])])
+  );
+}
+
+export function deepFreeze<T>(value: T): Readonly<T> {
+  const candidate: unknown = value;
+  if (candidate === null || typeof candidate !== 'object' || Object.isFrozen(candidate)) {
+    return value;
+  }
+  for (const item of Object.values(candidate)) deepFreeze(item);
+  Object.freeze(candidate);
+  return value;
+}

package/src/agent-cli-provider/omp/sdk-settings.ts

@@ -0,0 +1,33 @@
+export {
+  OMP_AUTH_BROKER_ENV_NAMES,
+  OMP_SDK_REASONING_EFFORTS,
+  OMP_SDK_TOOL_IDS,
+} from './sdk-settings-types';
+export type {
+  ConfiguredOmpSdkSettings,
+  ExactOmpModelSelector,
+  OmpBrokerAuth,
+  OmpEnvironmentAuth,
+  OmpExecutionContext,
+  OmpHomeAuth,
+  OmpLevelOverride,
+  OmpModelDefinition,
+  OmpModelLevel,
+  OmpModelsConfig,
+  OmpNoneAuth,
+  OmpProviderConfig,
+  OmpReasoningEffort,
+  OmpSdkAuth,
+  OmpSdkSettings,
+  OmpSdkToolId,
+  OmpSettingsValidationContext,
+  OmpTransport,
+} from './sdk-settings-types';
+export { parseExactOmpModelSelector } from './sdk-settings-selector';
+export {
+  compilePrivateOmpModelsYaml,
+  normalizeOmpSdkSettings,
+  OMP_SDK_SETTINGS_DEFAULTS,
+  resolveOmpSdkSettings,
+  validateOmpSdkSettings,
+} from './sdk-settings-normalize';