@apifuse/provider-sdk 2.2.0-beta.47 → 2.2.0-beta.49

package/src/engine.ts

@@ -0,0 +1,279 @@
+import { ProviderError } from "./errors.js";
+import {
+	OTEL_EXPORTER_OTLP_ENDPOINT,
+	OTEL_EXPORTER_OTLP_HEADERS,
+	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+	OTEL_EXPORTER_OTLP_TRACES_HEADERS,
+	OTEL_RESOURCE_ATTRIBUTES,
+	OTEL_SERVICE_NAME,
+} from "./runtime/otlp.js";
+import type {
+	AuthContext,
+	BrowserClient,
+	CredentialContext,
+	EnvContext,
+	HttpClient,
+	NativeContext,
+	OcrContext,
+	ProviderCache,
+	ProviderChoiceContext,
+	ProviderContext,
+	ProviderDefinition,
+	ProviderFilesContext,
+	ProviderRequestContext,
+	ProviderRuntimeState,
+	ResolverContext,
+	StealthClient,
+	SttContext,
+	TraceContext,
+} from "./types.js";
+
+/** Versioned envelope protocol used by out-of-process engine transports. */
+export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1" as const;
+
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
+	"APIFUSE__PROXY__SMARTPROXY_APP_KEY",
+	"APIFUSE__PROXY__NODEMAVEN_USERNAME",
+	"APIFUSE__PROXY__NODEMAVEN_PASSWORD",
+] as const;
+
+const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET = new Set<string>(
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+);
+
+/**
+ * Environment names are compared case-insensitively: Windows resolves `otel_exporter_otlp_headers`
+ * to the same variable as `OTEL_EXPORTER_OTLP_HEADERS`, so a mixed-case alias must be treated as
+ * the engine-owned name it resolves to.
+ */
+function canonicalEnvName(name: string): string {
+	return name.toUpperCase();
+}
+
+export function isEngineOwnedProxyCredentialName(name: string): boolean {
+	return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+
+/**
+ * Trace-export configuration owned by the engine and forbidden in provider
+ * declarations. The header variables carry collector credentials; the rest are
+ * engine deployment settings a provider has no reason to read.
+ */
+export const ENGINE_OWNED_TELEMETRY_ENV_NAMES = [
+	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+	OTEL_EXPORTER_OTLP_ENDPOINT,
+	OTEL_EXPORTER_OTLP_TRACES_HEADERS,
+	OTEL_EXPORTER_OTLP_HEADERS,
+	OTEL_SERVICE_NAME,
+	OTEL_RESOURCE_ATTRIBUTES,
+] as const;
+
+const ENGINE_OWNED_TELEMETRY_ENV_NAME_SET = new Set<string>(ENGINE_OWNED_TELEMETRY_ENV_NAMES);
+
+export function isEngineOwnedTelemetryEnvName(name: string): boolean {
+	return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export function isEngineOwnedEnvName(name: string): boolean {
+	return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+}
+
+/** Capture credentials in the engine host before constructing provider bindings. */
+export function readEngineProxyCredentials(
+	environment: Readonly<Record<string, string | undefined>> = process.env,
+): Readonly<Record<string, string>> {
+	return Object.fromEntries(
+		ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
+			const value = environment[name]?.trim();
+			return value ? [[name, value] as const] : [];
+		}),
+	);
+}
+
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export function createProviderEnvironment(
+	environment: Readonly<Record<string, string | undefined>>,
+	declaredNames: readonly string[],
+): Readonly<Record<string, string>> {
+	return Object.fromEntries(
+		declaredNames.flatMap((name) => {
+			if (isEngineOwnedEnvName(name)) return [];
+			const value = environment[name];
+			return value === undefined ? [] : [[name, value] as const];
+		}),
+	);
+}
+
+/**
+ * Request/response is the first remote transport lane. Stream and session
+ * handles are separate lanes so lifecycle-bearing capabilities are never
+ * disguised as ordinary JSON calls.
+ */
+export interface ProviderEngineTransport {
+	request<TResponse = unknown>(request: ProviderEngineRequest): Promise<TResponse>;
+	openStream?(request: ProviderEngineRequest): Promise<ReadableStream<Uint8Array>>;
+	openSession?(request: ProviderEngineRequest): Promise<ProviderEngineSession>;
+}
+
+export interface ProviderEngineRequest {
+	readonly version: typeof PROVIDER_ENGINE_PROTOCOL_VERSION;
+	readonly providerId: string;
+	readonly requestId: string;
+	readonly capability: ProviderCapabilityKey;
+	readonly method: string;
+	readonly payload: unknown;
+}
+
+export interface ProviderEngineSession {
+	request<TResponse = unknown>(method: string, payload: unknown): Promise<TResponse>;
+	close(): Promise<void>;
+}
+
+/** Capability implementations owned by the engine rather than provider code. */
+export interface ProviderEngineCapabilitySurface {
+	readonly http: HttpClient;
+	readonly browser: BrowserClient;
+	readonly stealth: StealthClient;
+	readonly stt: SttContext;
+	readonly ocr: OcrContext;
+	readonly resolver: ResolverContext;
+	readonly cache: ProviderCache;
+	readonly state: ProviderRuntimeState;
+}
+
+/** Engine-resident-only capabilities, kept separate from the portable surface. */
+export interface ProviderEngineResidentSurface {
+	readonly native: NativeContext;
+}
+
+export const PROVIDER_CAPABILITY_KEYS = [
+	"env",
+	"credential",
+	"http",
+	"files",
+	"native",
+	"cache",
+	"state",
+	"stealth",
+	"browser",
+	"auth",
+	"ocr",
+	"stt",
+	"resolver",
+	"choice",
+] as const;
+
+export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
+
+export type ProviderEngineBindingCandidates = Partial<
+	ProviderEngineCapabilitySurface &
+		ProviderEngineResidentSurface & {
+			readonly env: EnvContext;
+			readonly credential: CredentialContext;
+			readonly files: ProviderFilesContext;
+			readonly auth: AuthContext;
+			readonly choice: ProviderChoiceContext;
+		}
+> & {
+	readonly request?: ProviderRequestContext;
+	readonly trace: TraceContext;
+};
+
+export interface ProviderEngineAttachmentInput {
+	readonly provider: ProviderDefinition;
+	readonly bindings: ProviderEngineBindingCandidates;
+}
+
+/** Attachment boundary shared by in-process development and remote RPC bridges. */
+export interface ProviderEngine {
+	attach<TDeclaration extends object = Record<string, unknown>>(
+		input: ProviderEngineAttachmentInput,
+	): ProviderContext<TDeclaration>;
+}
+
+const CAPABILITY_KEY_SET = new Set<string>(PROVIDER_CAPABILITY_KEYS);
+
+function declaresCapability(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): boolean {
+	return Object.hasOwn(provider, capability) && provider[capability] !== undefined;
+}
+
+function attachmentError(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): ProviderError {
+	return new ProviderError(
+		`Provider engine could not attach declared capability "${capability}" for provider "${provider.id}"`,
+		{
+			code: "PROVIDER_ENGINE_ATTACHMENT_FAILED",
+			details: { providerId: provider.id, capability },
+			fix: `Configure the engine binding for "${capability}" before starting the provider.`,
+		},
+	);
+}
+
+function undeclaredCapabilityError(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): ProviderError {
+	return new ProviderError(
+		`Provider "${provider.id}" accessed undeclared capability "${capability}"; add the "${capability}" declaration`,
+		{
+			code: "PROVIDER_CAPABILITY_UNDECLARED",
+			details: { providerId: provider.id, capability },
+			fix: `Add ${capability}: {} to the provider declaration, or remove the access.`,
+		},
+	);
+}
+
+function attachInProcess<TDeclaration extends object>(
+	input: ProviderEngineAttachmentInput,
+): ProviderContext<TDeclaration> {
+	const { provider, bindings } = input;
+	if (provider.runtimeTarget === "vanilla" && declaresCapability(provider, "native")) {
+		throw new ProviderError(
+			`Provider "${provider.id}" cannot attach capability "native" to runtime target "vanilla"; native requires an engine-resident runtime`,
+			{
+				code: "PROVIDER_RUNTIME_CAPABILITY_CONFLICT",
+				details: { providerId: provider.id, capability: "native", runtimeTarget: "vanilla" },
+			},
+		);
+	}
+
+	const context: Record<PropertyKey, unknown> = { trace: bindings.trace };
+	if (bindings.request !== undefined) context.request = bindings.request;
+	for (const capability of PROVIDER_CAPABILITY_KEYS) {
+		if (!declaresCapability(provider, capability)) continue;
+		const binding = bindings[capability];
+		if (binding === undefined || binding === null) throw attachmentError(provider, capability);
+		context[capability] = binding;
+	}
+
+	return new Proxy(context, {
+		get(target, property, receiver) {
+			if (
+				typeof property === "string" &&
+				CAPABILITY_KEY_SET.has(property) &&
+				!declaresCapability(provider, property as ProviderCapabilityKey)
+			) {
+				throw undeclaredCapabilityError(provider, property as ProviderCapabilityKey);
+			}
+			return Reflect.get(target, property, receiver);
+		},
+		has(target, property) {
+			if (typeof property === "string" && CAPABILITY_KEY_SET.has(property)) {
+				return declaresCapability(provider, property as ProviderCapabilityKey);
+			}
+			return Reflect.has(target, property);
+		},
+	}) as ProviderContext<TDeclaration>;
+}
+
+/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+export function createInProcessProviderEngine(): ProviderEngine {
+	return { attach: attachInProcess };
+}

package/src/index.ts

@@ -120,6 +120,7 @@ export type {
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
+export * from "./engine.js";
 export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
@@ -260,7 +261,12 @@ export {
 	type ServeOptions,
 	serve,
 } from "./server/serve.js";
-export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
+export {
+	DEFAULT_STEALTH_BROWSER,
+	DEFAULT_STEALTH_OS,
+	getStealthProfile,
+	listStealthProfiles,
+} from "./stealth/profiles.js";
 export * from "./stream.js";
 export type {
 	ApiFuseResponse,
@@ -349,23 +355,20 @@ export type {
 	OcrRecognizeRequest,
 	OcrResult,
 	OcrWarning,
-	OperationAnnotations,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
 	OperationDefinition,
 	OperationDeprecationMetadata,
-	OperationDocMeta,
+	OperationExample,
 	OperationErrorCode,
 	ProviderErrorStatus,
 	OperationHandlerResult,
-	OperationInputExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,
 	OperationObservabilitySensitiveConfig,
 	OperationRelationships,
 	OperationRiskClass,
 	OperationSensitivePath,
-	OperationToolRouterMetadata,
 	OperationTransport,
 	OperationTransportKind,
 	ProbeInterval,
@@ -413,6 +416,7 @@ export type {
 	ProviderResolvedFile,
 	ProviderResolverConfig,
 	ProviderResolverVendor,
+	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
 	ProviderStateDurationString,
@@ -437,11 +441,15 @@ export type {
 	StateValue,
 	StateWriteOptions,
 	StealthClient,
+	StealthBrowser,
 	StealthCookieStore,
 	StealthCookieStoreV1,
 	StealthFetchOptions,
 	StealthPlatform,
 	StealthProfile,
+	StealthProfileDescriptor,
+	StealthProfileSelection,
+	StealthOS,
 	StealthRedirectHop,
 	StealthRedirectRunOptions,
 	StealthRedirectRunResult,

package/src/lint.ts

@@ -8,6 +8,11 @@ import {
 } from "./error-resolution.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
+import type {
+	AuthMode,
+	OperationApprovalPolicy,
+	OperationRiskClass,
+} from "./types.js";
 
 const requireModule = createRequire(import.meta.url);
 // `typeof import(...)` keeps the type without emitting a static import: the
@@ -28,6 +33,22 @@ type AuthModeLike =
 	| "oauth2_proxied"
 	| "api-key";
 
+const CREDENTIAL_BEARING_AUTH_MODES = [
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] satisfies readonly AuthMode[];
+
+function isCredentialBearingAuthMode(mode: AuthModeLike | undefined): boolean {
+	return CREDENTIAL_BEARING_AUTH_MODES.some((credentialMode) => credentialMode === mode);
+}
+
+function defaultApprovalPolicy(riskClass: OperationRiskClass): OperationApprovalPolicy {
+	if (riskClass === "read") return "never";
+	if (riskClass === "write") return "risk-based";
+	return "always";
+}
+
 type ProviderAuthLike = {
 	mode?: AuthModeLike;
 	flow?: {
@@ -699,21 +720,6 @@ function collectSchemaDescriptionKeyDiagnostics(
 	return diagnostics;
 }
 
-function isComplexSchema(schema: unknown, seen = new Set<SchemaLike>()): boolean {
-	if (!isSchema(schema) || seen.has(schema)) {
-		return false;
-	}
-
-	seen.add(schema);
-	const children = getChildSchemas(schema);
-	const hasNestedComposite = children.some(({ schema: child }) => {
-		const childChildren = getChildSchemas(child);
-		return childChildren.length > 0;
-	});
-
-	return hasNestedComposite || children.some(({ schema: child }) => isComplexSchema(child, seen));
-}
-
 function hasBidirectionalFixtures(fixtures: unknown): boolean {
 	if (!fixtures || typeof fixtures !== "object") {
 		return true;
@@ -1024,11 +1030,11 @@ function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLit
 function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): string {
 	switch (finding.kind) {
 		case "profile":
-			return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Use the matching intent alias instead: "chrome-desktop", "firefox-desktop", "safari-desktop", or "safari-mobile".`;
+			return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Select the browser and OS structurally, for example stealth: { browser: "chrome", os: "macos" }.`;
 		case "user-agent":
-			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the matching intent profile, for example getStealthProfile("chrome-desktop").userAgent.`;
+			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the structured profile, for example getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
 		case "sec-ch-ua":
-			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from an intent profile such as "chrome-desktop"; derive any explicit User-Agent with getStealthProfile("chrome-desktop").userAgent.';
+			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }; derive any explicit User-Agent with getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
 	}
 }
 
@@ -1283,7 +1289,7 @@ function collectLiteralThrownErrorCodes(source: string): string[] {
  * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
  * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
  * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
- * nor declared in any operation's docs.errorCodes. At runtime such a code
+ * nor declared in any operation's errorCodes. At runtime such a code
  * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
  *
  * A throw site cannot be attributed to a specific operation statically —
@@ -1303,7 +1309,7 @@ function lintUndeclaredThrownErrorCodes(provider: {
 		{
 			handler?: unknown;
 			source?: string;
-			docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
+			errorCodes?: ReadonlyArray<{ code: string }>;
 		}
 	>;
 }): LintDiagnostic[] {
@@ -1312,7 +1318,7 @@ function lintUndeclaredThrownErrorCodes(provider: {
 		...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
 	]);
 	for (const operation of Object.values(provider.operations ?? {})) {
-		for (const entry of operation.docs?.errorCodes ?? []) {
+		for (const entry of operation.errorCodes ?? []) {
 			if (typeof entry?.code === "string") {
 				knownCodes.add(entry.code);
 			}
@@ -1349,7 +1355,7 @@ function lintUndeclaredThrownErrorCodes(provider: {
 				rule: "thrown-error-code-undeclared",
 				level: "warn",
 				field,
-				message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's docs.errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's docs.errorCodes with status and retryable.`,
+				message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's errorCodes with status and retryable.`,
 			});
 		}
 	}
@@ -1357,68 +1363,22 @@ function lintUndeclaredThrownErrorCodes(provider: {
 }
 
 export function lintOperation(op: {
-	description?: string;
 	descriptionKey?: string;
-	whenToUse?: readonly string[];
 	whenToUseKeys?: readonly string[];
-	whenNotToUse?: readonly string[];
 	whenNotToUseKeys?: readonly string[];
 	input: unknown;
 	output: unknown;
 	fixtures?: unknown;
-	inputExamples?: readonly unknown[];
-	derivations?: Record<string, string>;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
-	const description = op.description ?? "";
 	const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
 
-	if (description.trim().length > 0 && !hasDescriptionKey) {
+	if (!hasDescriptionKey) {
 		diagnostics.push({
-			rule: "operation-description-raw-prose",
+			rule: "description-key-required",
 			level: "error",
-			field: "description",
-			message: "Operation description must use descriptionKey instead of raw static prose.",
-		});
-	}
-
-	if (!hasDescriptionKey && description.length < 150) {
-		diagnostics.push({
-			rule: "description-min-length",
-			level: "error",
-			field: "description",
-			message: "Operation description must be at least 150 characters.",
-		});
-	}
-
-	if ((op.whenToUse?.length ?? 0) > 0 && !(op.whenToUseKeys?.length ?? 0)) {
-		diagnostics.push({
-			rule: "operation-when-to-use-raw-prose",
-			level: "error",
-			field: "whenToUse",
-			message: "Operation whenToUse must use whenToUseKeys instead of raw static prose.",
-		});
-	}
-
-	if ((op.whenNotToUse?.length ?? 0) > 0 && !(op.whenNotToUseKeys?.length ?? 0)) {
-		diagnostics.push({
-			rule: "operation-when-not-to-use-raw-prose",
-			level: "error",
-			field: "whenNotToUse",
-			message: "Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
-		});
-	}
-
-	const lowerDescription = description.toLowerCase();
-	if (
-		!hasDescriptionKey &&
-		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
-	) {
-		diagnostics.push({
-			rule: "description-has-when-clause",
-			level: "warn",
-			field: "description",
-			message: 'Operation description should include both "use" and "when".',
+			field: "descriptionKey",
+			message: "Operation must declare a locale-backed descriptionKey.",
 		});
 	}
 
@@ -1436,15 +1396,6 @@ export function lintOperation(op: {
 		});
 	}
 
-	if (isComplexSchema(op.input) && (op.inputExamples?.length ?? 0) < 2) {
-		diagnostics.push({
-			rule: "complex-input-has-examples",
-			level: "warn",
-			field: "inputExamples",
-			message: "Complex input schemas should provide at least 2 input examples.",
-		});
-	}
-
 	for (const field of uniqueFields(collectUnmarkedSensitiveFields(op.input, "input"))) {
 		diagnostics.push({
 			rule: "sensitive-field-unmarked",
@@ -1546,20 +1497,18 @@ export function lintProvider(
 		operations?: Record<
 			string,
 			{
-				description?: string;
 				descriptionKey?: string;
-				whenToUse?: readonly string[];
 				whenToUseKeys?: readonly string[];
-				whenNotToUse?: readonly string[];
 				whenNotToUseKeys?: readonly string[];
+				connectionMode?: "none" | "optional" | "required";
+				riskClass?: OperationRiskClass;
+				approval?: OperationApprovalPolicy;
 				input: unknown;
 				output: unknown;
 				fixtures?: unknown;
-				inputExamples?: readonly unknown[];
-				derivations?: Record<string, string>;
 				handler?: unknown;
 				source?: string;
-				docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
+				errorCodes?: ReadonlyArray<{ code: string }>;
 			}
 		>;
 		meta?: {
@@ -1591,6 +1540,28 @@ export function lintProviderWithInformation(
 
 	if (provider.operations) {
 		const authMode = provider.auth?.mode;
+		for (const [operationKey, operation] of Object.entries(provider.operations)) {
+			if (isCredentialBearingAuthMode(authMode) && operation.connectionMode === undefined) {
+				diagnostics.push({
+					rule: "mixed-auth-connection-mode-required",
+					level: "error",
+					field: `operations.${operationKey}.connectionMode`,
+					message: `Provider "${provider.id ?? "unknown"}" uses credential-bearing auth.mode "${authMode}"; operation "${operationKey}" must declare connectionMode explicitly.`,
+				});
+			}
+			if (
+				operation.riskClass !== undefined &&
+				operation.approval !== undefined &&
+				operation.approval === defaultApprovalPolicy(operation.riskClass)
+			) {
+				diagnostics.push({
+					rule: "redundant-approval",
+					level: "error",
+					field: `operations.${operationKey}.approval`,
+					message: `Operation "${operationKey}" approval "${operation.approval}" repeats the default for riskClass "${operation.riskClass}"; omit approval unless it is a deliberate override.`,
+				});
+			}
+		}
 		// Every authenticated mode owns an auth.flow; `oauth2_proxied` was
 		// previously exempt, which let auth-lifecycle operations ship on
 		// proxied providers unchecked.
@@ -1620,17 +1591,12 @@ export function lintProviderWithInformation(
 		...Object.entries(provider.operations).flatMap(([operationKey, operation]) =>
 			[
 				...lintOperation({
-					description: operation.description ?? "",
 					descriptionKey: operation.descriptionKey,
-					whenToUse: operation.whenToUse,
 					whenToUseKeys: operation.whenToUseKeys,
-					whenNotToUse: operation.whenNotToUse,
 					whenNotToUseKeys: operation.whenNotToUseKeys,
 					input: operation.input,
 					output: operation.output,
 					fixtures: operation.fixtures,
-					inputExamples: operation.inputExamples,
-					derivations: operation.derivations,
 				}),
 				...lintPublicSchemaFieldNames(
 					provider.id,

package/src/provider.ts

@@ -129,6 +129,29 @@ export {
 	TransportError,
 	ValidationError,
 } from "./errors.js";
+export {
+	createProviderEnvironment,
+	createInProcessProviderEngine,
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_TELEMETRY_ENV_NAMES,
+	isEngineOwnedEnvName,
+	isEngineOwnedProxyCredentialName,
+	isEngineOwnedTelemetryEnvName,
+	PROVIDER_CAPABILITY_KEYS,
+	PROVIDER_ENGINE_PROTOCOL_VERSION,
+	readEngineProxyCredentials,
+} from "./engine.js";
+export type {
+	ProviderCapabilityKey,
+	ProviderEngine,
+	ProviderEngineAttachmentInput,
+	ProviderEngineBindingCandidates,
+	ProviderEngineCapabilitySurface,
+	ProviderEngineRequest,
+	ProviderEngineResidentSurface,
+	ProviderEngineSession,
+	ProviderEngineTransport,
+} from "./engine.js";
 export {
 	getProviderLocalePath,
 	providerLocaleKey,
@@ -203,17 +226,15 @@ export type {
 	OperationApprovalPolicy,
 	OperationContractMetadata,
 	OperationDefinition,
-	OperationDocMeta,
+	OperationExample,
 	OperationErrorCode,
 	ProviderErrorStatus,
-	OperationInputExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,
 	OperationObservabilitySensitiveConfig,
 	OperationRelationships,
 	OperationRiskClass,
 	OperationSensitivePath,
-	OperationToolRouterMetadata,
 	OperationTransport,
 	ProviderAccessVisibility,
 	ProviderChoiceBindingOptions,
@@ -238,6 +259,7 @@ export type {
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
 	ProviderResolvedFile,
+	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
 	ProviderStateNamespace,