@the-open-engine/zeroshot 6.15.0 → 6.16.0

package/src/agent-cli-provider/adapters/index.ts

@@ -1,5 +1,11 @@
 import { stripTimestampPrefix } from '../log-prefix';
-import { getProviderRegistryEntry, normalizeProviderName, providerIds } from '../provider-registry';
+import { UnsupportedProviderCapabilityError } from '../errors';
+import {
+  getProviderRegistryEntry,
+  normalizeProviderName,
+  providerIds,
+  supportsProviderCapability,
+} from '../provider-registry';
 import type {
   BuildProviderCommandOptions,
   CommandSpec,
@@ -52,7 +58,15 @@ export function buildProviderCommand(
   context: string,
   options?: BuildProviderCommandOptions
 ): CommandSpec {
-  return getProviderAdapter(providerName).buildCommand(context, options);
+  const adapter = getProviderAdapter(providerName);
+  if (options?.webSearch !== undefined && !supportsProviderCapability(adapter.id, 'webSearch')) {
+    throw new UnsupportedProviderCapabilityError(
+      adapter.id,
+      'webSearch',
+      `Provider ${adapter.id} does not expose provider-controlled native web search; remove options.webSearch.`
+    );
+  }
+  return adapter.buildCommand(context, options);
 }
 
 export function parseProviderChunk(

package/src/agent-cli-provider/adapters/opencode.ts

@@ -1,3 +1,5 @@
+import { contractError } from '../contract-errors';
+import { UnsupportedProviderCapabilityError } from '../errors';
 import { appendJsonSchemaPrompt } from '../schema';
 import {
   getNumber,
@@ -20,8 +22,8 @@ import {
   classifyBaseProviderError,
   commandSpec,
   createParserState,
+  isCliVersionAtLeast,
   optionFeatures,
-  unsupportedSessionControlWarnings,
   warning,
 } from './common';
 import {
@@ -32,7 +34,10 @@ import {
   validateModelId,
 } from './opencode-models';
 
-function detectCliFeatures(helpText?: string | null): OpencodeCliFeatures {
+function detectCliFeatures(
+  helpText?: string | null,
+  versionText?: string | null
+): OpencodeCliFeatures {
   const help = helpText ?? '';
   const unknown = !help;
   return {
@@ -43,6 +48,8 @@ function detectCliFeatures(helpText?: string | null): OpencodeCliFeatures {
     supportsDir: unknown ? false : /--dir\b/.test(help),
     supportsCwd: unknown ? false : /--cwd\b/.test(help),
     supportsAutoApprove: false,
+    supportsResume: !unknown && /--session\b/.test(help) && /--continue\b/.test(help),
+    supportsWebSearch: isCliVersionAtLeast(versionText, '1.0.137'),
     unknown,
   };
 }
@@ -76,7 +83,7 @@ function addOpencodeOptionalArgs(args: string[], options: BuildProviderCommandOp
 
 function collectOpencodeWarnings(options: BuildProviderCommandOptions): WarningMetadata[] {
   const features = optionFeatures(options);
-  const warnings: WarningMetadata[] = unsupportedSessionControlWarnings('opencode', options);
+  const warnings: WarningMetadata[] = [];
   if (options.modelSpec?.reasoningEffort && features.supportsVariant === false) {
     warnings.push(
       warning(
@@ -89,19 +96,67 @@ function collectOpencodeWarnings(options: BuildProviderCommandOptions): WarningM
   return warnings;
 }
 
+function addSessionArgs(args: string[], options: BuildProviderCommandOptions): void {
+  const hasResumeSessionId = options.resumeSessionId !== undefined;
+  if (!hasResumeSessionId && !options.continueSession) return;
+  const field = hasResumeSessionId ? 'options.resumeSessionId' : 'options.continueSession';
+  if (hasResumeSessionId && options.resumeSessionId?.trim().length === 0) {
+    throw contractError({
+      code: 'invalid-field',
+      field,
+      exitCode: 2,
+      message: 'options.resumeSessionId must be a non-empty OpenCode session ID.',
+    });
+  }
+  if (optionFeatures(options).supportsResume === false) {
+    throw contractError({
+      code: 'invalid-field',
+      field,
+      exitCode: 2,
+      message:
+        'OpenCode CLI cannot safely run continuation context because this installation lacks run --session/--continue.',
+    });
+  }
+  if (options.resumeSessionId) {
+    args.push('--session', options.resumeSessionId);
+  } else {
+    args.push('--continue');
+  }
+}
+
+function webSearchEnv(options: BuildProviderCommandOptions): Readonly<Record<string, string>> {
+  if (options.webSearch !== true) return {};
+  if (optionFeatures(options).supportsWebSearch !== true) {
+    throw new UnsupportedProviderCapabilityError(
+      'opencode',
+      'webSearch',
+      'OpenCode web search requires a parseable OpenCode CLI version >= 1.0.137. Update OpenCode or set providerSettings.opencode.webSearch to false.'
+    );
+  }
+  return { OPENCODE_ENABLE_EXA: '1' };
+}
+
+function extractSessionId(line: string): string | null {
+  const event = tryParseJson(line.trim());
+  if (!isRecord(event)) return null;
+  const sessionId = getString(event, 'sessionID') ?? getString(event, 'sessionId');
+  return sessionId?.trim() || null;
+}
+
 function buildCommand(context: string, options: BuildProviderCommandOptions = {}): CommandSpec {
   const finalContext = options.jsonSchema
     ? appendJsonSchemaPrompt(context, options.jsonSchema)
     : context;
   const args: string[] = ['run'];
   addOpencodeOptionalArgs(args, options);
+  addSessionArgs(args, options);
 
   args.push(finalContext);
 
   return commandSpec({
     binary: 'opencode',
     args,
-    env: {},
+    env: webSearchEnv(options),
     ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
     warnings: collectOpencodeWarnings(options),
   });
@@ -226,6 +281,7 @@ export const opencodeAdapter: ProviderAdapter = {
   defaultMinLevel: 'level1',
   detectCliFeatures,
   buildCommand,
+  extractSessionId,
   parseEvent,
   createParserState: () => createParserState('opencode'),
   resolveModelSpec,

package/src/agent-cli-provider/contract-actions.ts

@@ -23,6 +23,10 @@ import type { ProcessRunner } from './process-runner';
 
 function runBuildCommand(request: RequestData): ContractEnvelope {
   const { adapter, commandSpec, options } = buildCommandSpec(request);
+  const webSearch = {
+    requested: options.webSearch === true,
+    effective: options.webSearch === true && options.cliFeatures?.supportsWebSearch === true,
+  };
   return successEnvelope({
     command: request.command ?? 'build-command',
     adapter,
@@ -31,11 +35,13 @@ function runBuildCommand(request: RequestData): ContractEnvelope {
     evidence: {
       outputFormat: options.outputFormat ?? null,
       schemaMode: schemaMode(options),
+      configuration: { webSearch },
     },
     result: {
       commandSpec,
       outputFormat: options.outputFormat ?? null,
       schemaMode: schemaMode(options),
+      configuration: { webSearch },
     },
   });
 }
@@ -43,11 +49,15 @@ function runBuildCommand(request: RequestData): ContractEnvelope {
 function runProbe(request: RequestData): ContractEnvelope {
   const adapter = adapterForProvider(request.provider);
   const helpText = typeof request.raw.helpText === 'string' ? request.raw.helpText : null;
-  const runtimeProbe = helpText === null ? probeRuntimeProviderCli(adapter.id) : null;
-  const capabilities =
-    runtimeProbe === null
-      ? adapter.detectCliFeatures(helpText)
-      : runtimeProbe.capabilities;
+  const versionText = typeof request.raw.versionText === 'string' ? request.raw.versionText : '';
+  const runtimeProbe =
+    helpText === null
+      ? probeRuntimeProviderCli(adapter.id)
+      : probeRuntimeProviderCli(adapter.id, {
+          available: true,
+          helpText,
+          versionText,
+        });
   return successEnvelope({
     command: request.command ?? 'probe',
     adapter,
@@ -60,10 +70,11 @@ function runProbe(request: RequestData): ContractEnvelope {
       },
       contractVersion: providerExecutableSchemaVersion,
       adapterVersion: adapter.adapterVersion,
-      available: runtimeProbe?.available ?? true,
-      helpText: runtimeProbe?.helpText ?? helpText,
-      versionText: runtimeProbe?.versionText ?? null,
-      capabilities,
+      available: runtimeProbe.available,
+      helpText: runtimeProbe.helpText,
+      versionText: runtimeProbe.versionText,
+      capabilities: runtimeProbe.capabilities,
+      configuration: runtimeProbe.configuration,
       credentials: adapter.credentialEnvKeys.map((key) => ({
         key,
         present: Boolean(request.env[key] ?? process.env[key]),

package/src/agent-cli-provider/contract-fallback.ts

@@ -6,6 +6,7 @@ import {
   type ContractErrorObject,
   type ContractEnvelope,
 } from './contract-envelope';
+import { UnsupportedProviderCapabilityError } from './errors';
 import { getString, isRecord, parseJson, unknownToMessage } from './json';
 import { mergeRedactions, redactString } from './redaction';
 import type { ProviderAdapter } from './types';
@@ -77,6 +78,14 @@ function errorObject(requestError: ContractRequestError): ContractErrorObject {
 
 export function requestErrorFromUnknown(error: unknown): ContractRequestError {
   if (error instanceof ContractRequestError) return error;
+  if (error instanceof UnsupportedProviderCapabilityError) {
+    return contractError({
+      code: error.code,
+      message: error.message,
+      exitCode: 4,
+      field: 'options.webSearch',
+    });
+  }
   return contractError({
     code: 'internal-error',
     message: unknownToMessage(error),

package/src/agent-cli-provider/contract-options.ts

@@ -44,6 +44,7 @@ const CLI_FEATURE_FIELDS = [
   'supportsAddDir',
   'supportsMcpConfig',
   'supportsResume',
+  'supportsWebSearch',
   'supportsBundledRunner',
   'supportsAcpStdio',
   'supportsPromptImages',
@@ -210,6 +211,7 @@ function normalizeBuildOptions(value: Record<string, unknown>): BuildProviderCom
     'continueSession',
     optionalBooleanValue(value.continueSession, 'options.continueSession')
   );
+  addDefined(result, 'webSearch', optionalBooleanValue(value.webSearch, 'options.webSearch'));
   addDefined(
     result,
     'claudeSettingsFile',

package/src/agent-cli-provider/errors.ts

@@ -1,6 +1,20 @@
 import { getNumber, getRecord, getString, isRecord, unknownToMessage } from './json';
 import type { ErrorClassification } from './types';
 
+export class UnsupportedProviderCapabilityError extends Error {
+  readonly code = 'unsupported-capability';
+  readonly permanent = true;
+  readonly provider: string;
+  readonly capability: string;
+
+  constructor(provider: string, capability: string, message: string) {
+    super(message);
+    this.name = 'UnsupportedProviderCapabilityError';
+    this.provider = provider;
+    this.capability = capability;
+  }
+}
+
 const BASE_RETRYABLE_PATTERNS: readonly RegExp[] = [
   /rate.?limit/i,
   /\b429\b/i,

package/src/agent-cli-provider/index.ts

@@ -102,6 +102,7 @@ export type {
   ToolCallEvent,
   ToolResultEvent,
   WarningMetadata,
+  WebSearchAttestation,
 } from './types';
 
 import type { AgentCliProviderHelperMetadata } from './types';

package/src/agent-cli-provider/provider-registry.ts

@@ -20,6 +20,7 @@ export interface ProviderCapabilities {
   readonly thinkingMode: ProviderCapabilityState;
   readonly reasoningEffort: ProviderCapabilityState;
   readonly sessionResume: ProviderCapabilityState;
+  readonly webSearch: ProviderCapabilityState;
 }
 
 interface FixedProviderCommandSpec {
@@ -102,6 +103,7 @@ const STANDARD_CAPABILITIES: Readonly<
     | 'streamJson'
     | 'thinkingMode'
     | 'sessionResume'
+    | 'webSearch'
   >
 > = {
   dockerIsolation: true,
@@ -110,6 +112,7 @@ const STANDARD_CAPABILITIES: Readonly<
   streamJson: true,
   thinkingMode: true,
   sessionResume: false,
+  webSearch: false,
 };
 
 const CLAUDE_DOCKER_ENV_PASSTHROUGH = [
@@ -203,12 +206,15 @@ export const providerRegistry = [
     authInstructions: 'codex login',
     credentialPaths: ['~/.config/codex', '~/.codex'],
     credentialEnvKeys: codexAdapter.credentialEnvKeys,
-    settingsFields: [],
+    settingsFields: ['webSearch'],
+    settingsDefaults: { webSearch: false },
+    settingsValidator: (settings): string | null => validateWebSearchSettings('codex', settings),
     capabilities: {
       ...STANDARD_CAPABILITIES,
       jsonSchema: true,
       reasoningEffort: true,
       sessionResume: true,
+      webSearch: true,
     },
     docs: {
       label: 'Codex',
@@ -326,11 +332,15 @@ export const providerRegistry = [
     authInstructions: 'opencode auth login',
     credentialPaths: ['~/.local/share/opencode'],
     credentialEnvKeys: opencodeAdapter.credentialEnvKeys,
-    settingsFields: [],
+    settingsFields: ['webSearch'],
+    settingsDefaults: { webSearch: false },
+    settingsValidator: (settings): string | null => validateWebSearchSettings('opencode', settings),
     capabilities: {
       ...STANDARD_CAPABILITIES,
       jsonSchema: 'experimental',
       reasoningEffort: true,
+      sessionResume: true,
+      webSearch: true,
     },
     docs: {
       label: 'Opencode',
@@ -472,6 +482,14 @@ export const providerRegistry = [
   },
 ] as const satisfies readonly ProviderRegistryEntry[];
 
+function validateWebSearchSettings(
+  provider: 'codex' | 'opencode',
+  settings: Record<string, unknown>
+): string | null {
+  if (settings.webSearch === undefined || typeof settings.webSearch === 'boolean') return null;
+  return `providerSettings.${provider}.webSearch must be a boolean`;
+}
+
 type RegistryProviderId = (typeof providerRegistry)[number]['id'];
 type RegistryProviderAlias = (typeof providerRegistry)[number]['aliases'][number];
 

package/src/agent-cli-provider/single-agent-runtime.ts

@@ -1,4 +1,5 @@
 import { getProviderAdapter } from './adapters';
+import { UnsupportedProviderCapabilityError } from './errors';
 import { normalizeGatewayBuildOptions, resolveGatewayConfiguration } from './gateway-tools';
 import { isRecord } from './json';
 import {
@@ -19,6 +20,7 @@ import type {
   ProviderId,
   ResolvedGatewayBuildOptions,
   ReasoningEffort,
+  WebSearchAttestation,
 } from './types';
 
 type UnknownFunction = (...args: readonly unknown[]) => unknown;
@@ -32,6 +34,7 @@ interface RuntimeProviderSettings {
   readonly defaultLevel?: ModelLevel;
   readonly levelOverrides: LevelOverrides;
   readonly gateway?: GatewayBuildOptions;
+  readonly webSearch?: boolean;
 }
 
 interface RuntimeCommandContext {
@@ -50,6 +53,9 @@ export interface PreparedSingleAgentProviderCommand {
   readonly commandSpec: CommandSpec;
   readonly options: BuildProviderCommandOptions;
   readonly cliFeatures: CliFeatureOverrides;
+  readonly configuration: {
+    readonly webSearch: WebSearchAttestation;
+  };
 }
 
 export interface RuntimeProviderProbe {
@@ -57,6 +63,15 @@ export interface RuntimeProviderProbe {
   readonly helpText: string;
   readonly versionText: string;
   readonly capabilities: ProviderCliFeatures;
+  readonly configuration: {
+    readonly webSearch: WebSearchAttestation;
+  };
+}
+
+interface RuntimeProbeEvidence {
+  readonly available?: boolean;
+  readonly helpText: string;
+  readonly versionText: string;
 }
 
 type MutableModelSpec = {
@@ -91,7 +106,13 @@ export function prepareSingleAgentProviderCommand(
     adapter.id,
     baseOptions.cwd ?? process.cwd()
   );
-  const cliFeatures = resolveRuntimeCliFeatures(adapter.id, baseOptions.cliFeatures);
+  const requestedWebSearch = baseOptions.webSearch ?? providerSettings.webSearch;
+  assertWebSearchDeclared(adapter.id, requestedWebSearch);
+  const cliFeatures = resolveRuntimeCliFeatures(
+    adapter.id,
+    baseOptions.cliFeatures,
+    requestedWebSearch === true
+  );
   const authEnv = baseOptions.authEnv ?? resolveRuntimeAuthEnv(adapter.id, settings);
   const options = buildRuntimeOptions(baseOptions, adapter, providerSettings, {
     cliFeatures,
@@ -101,6 +122,9 @@ export function prepareSingleAgentProviderCommand(
     adapter,
     options,
     cliFeatures,
+    configuration: {
+      webSearch: webSearchAttestation(options),
+    },
     commandSpec: adapter.buildCommand(input.context, options),
   };
 }
@@ -111,22 +135,35 @@ export function detectRuntimeProviderCliFeatures(provider: string): ProviderCliF
 
 function resolveRuntimeCliFeatures(
   provider: ProviderId,
-  overrides: CliFeatureOverrides | undefined
+  overrides: CliFeatureOverrides | undefined,
+  webSearchRequested: boolean
 ): CliFeatureOverrides {
   if (provider === 'gateway') {
+    const detected = detectRuntimeProviderCliFeatures(provider);
     return {
-      ...detectRuntimeProviderCliFeatures(provider),
+      ...detected,
       ...overrides,
       supportsBundledRunner: true,
+      supportsWebSearch: false,
     };
   }
-  if (getProviderRegistryEntry(provider).invoke.lane !== 'acp-stdio') {
-    return overrides ?? detectRuntimeProviderCliFeatures(provider);
+  if (getProviderRegistryEntry(provider).invoke.lane === 'acp-stdio') {
+    const detected = detectRuntimeProviderCliFeatures(provider);
+    if (overrides === undefined) return detected;
+    return mergeAcpFailClosedCliFeatures(detected, overrides);
   }
-
+  if (overrides === undefined) return detectRuntimeProviderCliFeatures(provider);
+  if (!webSearchRequested) return overrides;
   const detected = detectRuntimeProviderCliFeatures(provider);
-  if (overrides === undefined) return detected;
-  return mergeAcpFailClosedCliFeatures(detected, overrides);
+  return {
+    ...overrides,
+    supportsResume:
+      'supportsResume' in detected &&
+      detected.supportsResume === true &&
+      overrides.supportsResume !== false,
+    supportsWebSearch:
+      detected.supportsWebSearch === true && overrides.supportsWebSearch !== false,
+  };
 }
 
 function mergeAcpFailClosedCliFeatures(
@@ -154,33 +191,61 @@ function mergeAcpFailClosedCliFeatures(
   };
 }
 
-export function probeRuntimeProviderCli(provider: string): RuntimeProviderProbe {
+export function probeRuntimeProviderCli(
+  provider: string,
+  evidence?: RuntimeProbeEvidence
+): RuntimeProviderProbe {
   const adapter = getProviderAdapter(provider);
   if (adapter.id === 'gateway') {
     return probeGatewayProvider(adapter);
   }
+  const requested = getProviderRegistryEntry(adapter.id).settingsFields.includes('webSearch')
+    ? runtimeProviderSettings(loadRuntimeSettings(), adapter.id, process.cwd()).webSearch === true
+    : false;
   const helpCommand = runtimeHelpCommand(adapter.id);
-  const commandAvailable = booleanResult(commandExistsFn(helpCommand.command));
+  const commandAvailable =
+    evidence === undefined
+      ? booleanResult(commandExistsFn(helpCommand.command))
+      : evidence.available !== false;
   if (!commandAvailable) {
+    const capabilities = attestedCliFeatures(adapter, '', '');
     return {
       available: false,
       helpText: '',
       versionText: '',
-      capabilities: adapter.detectCliFeatures(''),
+      capabilities,
+      configuration: {
+        webSearch: webSearchAttestation({ webSearch: requested, cliFeatures: capabilities }),
+      },
     };
   }
 
-  const helpText = stringResult(getHelpOutputFn(helpCommand.command, helpCommand.args)).trim();
-  const versionText = stringResult(
-    getVersionOutputFn(helpCommand.command, helpCommand.args)
-  ).trim();
+  const helpText =
+    evidence?.helpText ??
+    stringResult(getHelpOutputFn(helpCommand.command, helpCommand.args)).trim();
+  const versionText =
+    evidence?.versionText ??
+    stringResult(
+      getVersionOutputFn(
+        helpCommand.command,
+        getProviderRegistryEntry(adapter.id).capabilities.webSearch === true
+          ? []
+          : helpCommand.args
+      )
+    ).trim();
   const availabilityProbe = getProviderRegistryEntry(adapter.id).availabilityProbe ?? 'command';
+  const capabilities = attestedCliFeatures(adapter, helpText, versionText);
 
   return {
-    available: availabilityProbe === 'help-or-version' ? Boolean(helpText || versionText) : true,
+    available:
+      evidence?.available ??
+      (availabilityProbe === 'help-or-version' ? Boolean(helpText || versionText) : true),
     helpText,
     versionText,
-    capabilities: adapter.detectCliFeatures(helpText),
+    capabilities,
+    configuration: {
+      webSearch: webSearchAttestation({ webSearch: requested, cliFeatures: capabilities }),
+    },
   };
 }
 
@@ -197,10 +262,13 @@ function buildRuntimeOptions(
     providerSettings,
     modelSpec
   );
+  const webSearch = baseOptions.webSearch ?? providerSettings.webSearch;
+  assertWebSearchDeclared(adapter.id, webSearch);
   const resolved = {
     ...baseOptions,
     modelSpec,
     ...(gateway === undefined ? {} : { gateway }),
+    ...(webSearch === undefined ? {} : { webSearch }),
     cliFeatures: runtime.cliFeatures,
   };
   if (baseOptions.jsonSchema && !supportsProviderCapability(adapter.id, 'jsonSchema')) {
@@ -320,16 +388,20 @@ function runtimeProviderSettings(
     providerSettings.levelOverrides,
     `settings.providerSettings.${provider}.levelOverrides`
   );
+  const webSearch = optionalBoolean(
+    providerSettings.webSearch,
+    `settings.providerSettings.${provider}.webSearch`
+  );
   const gateway =
     provider === 'gateway'
       ? normalizeGatewayBuildOptions(providerSettings, 'settings.providerSettings.gateway', cwd)
       : undefined;
-  if (defaultLevel === undefined) {
-    return gateway === undefined ? { levelOverrides } : { levelOverrides, gateway };
-  }
-  return gateway === undefined
-    ? { defaultLevel, levelOverrides }
-    : { defaultLevel, levelOverrides, gateway };
+  const base = {
+    levelOverrides,
+    ...(gateway === undefined ? {} : { gateway }),
+    ...(webSearch === undefined ? {} : { webSearch }),
+  };
+  return defaultLevel === undefined ? base : { ...base, defaultLevel };
 }
 
 function runtimeHelpCommand(provider: ProviderId): CommandParts {
@@ -340,7 +412,7 @@ function runtimeHelpCommand(provider: ProviderId): CommandParts {
 }
 
 function probeGatewayProvider(adapter: ProviderAdapter): RuntimeProviderProbe {
-  const capabilities = adapter.detectCliFeatures('');
+  const capabilities = attestedCliFeatures(adapter, '', '');
   try {
     const settings = loadRuntimeSettings();
     const providerSettings = runtimeProviderSettings(settings, 'gateway', process.cwd());
@@ -354,6 +426,9 @@ function probeGatewayProvider(adapter: ProviderAdapter): RuntimeProviderProbe {
       helpText: 'Bundled gateway runner',
       versionText: process.version,
       capabilities,
+      configuration: {
+        webSearch: { requested: false, effective: false },
+      },
     };
   } catch {
     return {
@@ -361,10 +436,49 @@ function probeGatewayProvider(adapter: ProviderAdapter): RuntimeProviderProbe {
       helpText: 'Bundled gateway runner',
       versionText: process.version,
       capabilities,
+      configuration: {
+        webSearch: { requested: false, effective: false },
+      },
     };
   }
 }
 
+function attestedCliFeatures(
+  adapter: ProviderAdapter,
+  helpText: string,
+  versionText: string
+): ProviderCliFeatures {
+  const detected = adapter.detectCliFeatures(helpText, versionText);
+  return {
+    ...detected,
+    supportsWebSearch:
+      getProviderRegistryEntry(adapter.id).capabilities.webSearch === true &&
+      detected.supportsWebSearch === true,
+  };
+}
+
+function webSearchAttestation(options: {
+  readonly webSearch?: boolean;
+  readonly cliFeatures?: CliFeatureOverrides;
+}): WebSearchAttestation {
+  const requested = options.webSearch === true;
+  return {
+    requested,
+    effective: requested && options.cliFeatures?.supportsWebSearch === true,
+  };
+}
+
+function assertWebSearchDeclared(provider: ProviderId, requested: boolean | undefined): void {
+  if (requested === undefined || getProviderRegistryEntry(provider).capabilities.webSearch === true) {
+    return;
+  }
+  throw new UnsupportedProviderCapabilityError(
+    provider,
+    'webSearch',
+    `Provider ${provider} does not expose provider-controlled native web search; remove options.webSearch.`
+  );
+}
+
 function loadRuntimeSettings(): Record<string, unknown> {
   if (Object.prototype.hasOwnProperty.call(process.env, LEGACY_ISOLATED_PROVIDER_SETTINGS_ENV)) {
     throw new Error(
@@ -439,6 +553,12 @@ function addReasoningEffort(result: MutableModelSpec, value: unknown, field: str
   if (effort !== undefined) result.reasoningEffort = effort;
 }
 
+function optionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'boolean') return value;
+  throw new Error(`${field} must be a boolean.`);
+}
+
 function optionalModelLevel(value: unknown, field: string): ModelLevel | undefined {
   if (value === undefined) return undefined;
   if (value === 'level1' || value === 'level2' || value === 'level3') return value;