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

package/src/cli/templates/provider/README.md.tpl

@@ -113,9 +113,9 @@ Structured errors return an `error` object with `code`, `message`,
   `connection.secrets`, and read them with `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
-- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `wreq-js` internally
-  and supports Chrome, Firefox, and Safari profiles. Use `ctx.browser` only when
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with
+  structured SDK `stealth: { browser, os }` selection; the TypeScript stealth runtime uses
+  `wreq-js` internally and supports Chrome, Firefox, and Safari. Use `ctx.browser` only when
   the provider needs browser execution; TypeScript browser Providers use
   `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -4,6 +4,8 @@ import type { ProviderContext } from "../index";
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
 export const pingOperation = defineOperation<ProviderContext>()({
+  connectionMode: "none",
+  riskClass: "read",
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/src/config/loader.ts

@@ -13,7 +13,6 @@ import {
 	NODEMAVEN_PASSWORD_ENV,
 	NODEMAVEN_USERNAME_ENV,
 	type ProxyProtocol,
-	hasNodemavenCredentials,
 	nodemavenPoolSize,
 	synthesizeNodemavenProxy,
 } from "../runtime/proxy-nodemaven.js";
@@ -83,6 +82,8 @@ export type ProxyResolutionOptions = {
 	 */
 	proxyRefreshEpoch?: number;
 	telemetry?: ProxyTelemetrySink;
+	/** Engine-owned credential snapshot. Provider code must never populate this field. */
+	engineCredentials?: Readonly<Record<string, string>>;
 };
 
 export type ProxyCacheStatus =
@@ -527,7 +528,7 @@ export async function resolveProxyConfigAsync(
 		const poolIndex = vendorIndex === startVendorIndex ? startPoolIndex : 0;
 		const protocol = options.protocol ?? VENDOR_DEFAULT_PROTOCOL[vendor];
 
-		if (!vendorHasCredentials(vendor)) {
+		if (!vendorHasCredentials(vendor, options.engineCredentials)) {
 			options.telemetry?.recordProxyVendorFailover?.({
 				vendor,
 				nextVendor,
@@ -555,6 +556,7 @@ export async function resolveProxyConfigAsync(
 				protocol,
 				poolIndex,
 				refreshEpoch,
+				credentials: options.engineCredentials,
 			});
 		} catch (error) {
 			// Config/programming errors (invalid filter, etc.) are not vendor
@@ -805,9 +807,28 @@ function envDefaultProvider(): ProviderProxyProvider | undefined {
 	return (raw as ProviderProxyProvider | undefined) ?? undefined;
 }
 
-function vendorHasCredentials(vendor: ProxyVendorName): boolean {
-	if (vendor === "nodemaven") return hasNodemavenCredentials();
-	return Boolean(process.env[SMARTPROXY_APP_KEY_ENV]?.trim());
+function vendorHasCredentials(
+	vendor: ProxyVendorName,
+	credentials?: Readonly<Record<string, string>>,
+): boolean {
+	if (vendor === "nodemaven") {
+		return Boolean(
+			(credentials === undefined
+				? process.env[NODEMAVEN_USERNAME_ENV]
+				: credentials[NODEMAVEN_USERNAME_ENV]
+			)?.trim() &&
+				(credentials === undefined
+					? process.env[NODEMAVEN_PASSWORD_ENV]
+					: credentials[NODEMAVEN_PASSWORD_ENV]
+				)?.trim(),
+		);
+	}
+	return Boolean(
+		(credentials === undefined
+			? process.env[SMARTPROXY_APP_KEY_ENV]
+			: credentials[SMARTPROXY_APP_KEY_ENV]
+		)?.trim(),
+	);
 }
 
 function missingCredentialEnv(vendor: ProxyVendorName): string {
@@ -1710,7 +1731,11 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	}
 
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-	const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+	const appKey = (
+		options.engineCredentials === undefined
+			? process.env[SMARTPROXY_APP_KEY_ENV]
+			: options.engineCredentials[SMARTPROXY_APP_KEY_ENV]
+	)?.trim();
 	if (!appKey) return undefined;
 	const cacheKey = buildSmartproxyCacheKey(
 		policy,

package/src/contract-types.ts

@@ -30,17 +30,23 @@ export interface ProviderContractSnapshot {
 
 export interface ProviderContractOperation {
 	readonly id: string;
+	readonly connectionMode?: JsonValue;
+	readonly connectionExternalRefParam?: JsonValue;
+	readonly riskClass: JsonValue;
+	readonly approval?: JsonValue;
+	readonly timeoutMs?: JsonValue;
+	readonly titleKey?: JsonValue;
 	readonly descriptionKey?: JsonValue;
-	readonly docs?: JsonValue;
+	readonly summaryKey?: JsonValue;
+	readonly markdownKey?: JsonValue;
 	readonly whenToUseKeys?: JsonValue;
 	readonly whenNotToUseKeys?: JsonValue;
-	readonly derivations?: JsonValue;
-	readonly inputExamples?: JsonValue;
-	readonly annotations?: JsonValue;
+	readonly normalizationNotesKeys?: JsonValue;
+	readonly errorCodes?: JsonValue;
+	readonly examples?: JsonValue;
 	readonly contract?: JsonValue;
 	readonly tags?: JsonValue;
 	readonly relatedOperations?: JsonValue;
-	readonly toolRouter?: JsonValue;
 	readonly observability?: JsonValue;
 	readonly transport?: JsonValue;
 	readonly inputSchema: JsonValue;

package/src/contract.ts

@@ -82,17 +82,22 @@ function extractOperation(
 	operationId: string,
 	operation: OperationDefinition,
 ): ProviderContractOperation {
+	const connectionMode = toJsonValue(operation.connectionMode);
+	const connectionExternalRefParam = toJsonValue(operation.connectionExternalRefParam);
+	const approval = toJsonValue(operation.approval);
+	const timeoutMs = toJsonValue(operation.timeoutMs);
+	const titleKey = toJsonValue(operation.titleKey);
 	const descriptionKey = toJsonValue(operation.descriptionKey);
-	const docs = toJsonValue(operation.docs);
+	const summaryKey = toJsonValue(operation.summaryKey);
+	const markdownKey = toJsonValue(operation.markdownKey);
 	const whenToUseKeys = toJsonValue(operation.whenToUseKeys);
 	const whenNotToUseKeys = toJsonValue(operation.whenNotToUseKeys);
-	const derivations = toJsonValue(operation.derivations);
-	const inputExamples = toJsonValue(operation.inputExamples);
-	const annotations = toJsonValue(operation.annotations);
+	const normalizationNotesKeys = toJsonValue(operation.normalizationNotesKeys);
+	const errorCodes = toJsonValue(operation.errorCodes);
+	const examples = toJsonValue(operation.examples);
 	const contract = toJsonValue(operation.contract);
 	const tags = toJsonValue(operation.tags);
 	const relatedOperations = toJsonValue(operation.relatedOperations);
-	const toolRouter = toJsonValue(operation.toolRouter);
 	const observability = toJsonValue(operation.observability);
 	const transport = extractTransport(operation.transport);
 	const fixtures = toJsonValue(operation.fixtures);
@@ -105,17 +110,23 @@ function extractOperation(
 		id: operationId,
 		inputSchema: describeSchema(operation.input),
 		outputSchema: describeSchema(operation.output),
+		...(connectionMode === undefined ? {} : { connectionMode }),
+		...(connectionExternalRefParam === undefined ? {} : { connectionExternalRefParam }),
+		riskClass: operation.riskClass,
+		...(approval === undefined ? {} : { approval }),
+		...(timeoutMs === undefined ? {} : { timeoutMs }),
+		...(titleKey === undefined ? {} : { titleKey }),
 		...(descriptionKey === undefined ? {} : { descriptionKey }),
-		...(docs === undefined ? {} : { docs }),
+		...(summaryKey === undefined ? {} : { summaryKey }),
+		...(markdownKey === undefined ? {} : { markdownKey }),
 		...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
 		...(whenNotToUseKeys === undefined ? {} : { whenNotToUseKeys }),
-		...(derivations === undefined ? {} : { derivations }),
-		...(inputExamples === undefined ? {} : { inputExamples }),
-		...(annotations === undefined ? {} : { annotations }),
+		...(normalizationNotesKeys === undefined ? {} : { normalizationNotesKeys }),
+		...(errorCodes === undefined ? {} : { errorCodes }),
+		...(examples === undefined ? {} : { examples }),
 		...(contract === undefined ? {} : { contract }),
 		...(tags === undefined ? {} : { tags }),
 		...(relatedOperations === undefined ? {} : { relatedOperations }),
-		...(toolRouter === undefined ? {} : { toolRouter }),
 		...(observability === undefined ? {} : { observability }),
 		...(transport === undefined ? {} : { transport }),
 		...(fixtures === undefined ? {} : { fixtures }),

package/src/define.ts

@@ -6,6 +6,7 @@ import {
 } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
+import { isEngineOwnedProxyCredentialName, isEngineOwnedTelemetryEnvName } from "./engine.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
 import {
 	NativeEgressPolicyValidationError,
@@ -35,23 +36,22 @@ import type {
 	ProviderAccessConfig,
 	ProviderChallengeKind,
 	ProviderContext,
-	ProviderContextFor,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderOcrConfig,
 	ProviderProxyConfig,
-	ProviderProxyProvider,
 	ProviderPublicProfile,
 	ProviderResolverConfig,
 	ProviderResolverVendor,
 	ProviderReviewed,
+	ProviderRuntimeTarget,
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
 	ProviderSttConfig,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
-	StealthPlatform,
+	StealthProfileSelection,
 } from "./types.js";
 import {
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -95,6 +95,7 @@ interface ProviderImplementationProfile {
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
+const VALID_RUNTIME_TARGETS = ["vanilla", "engine"] as const;
 const VALID_AUTH_MODES = [
 	"none",
 	"platform-managed",
@@ -162,24 +163,10 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderCha
 	"akamai_sec_cpt",
 	"akamai_sensor",
 ] as const);
-const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
-const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
-const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
-// Per-vendor provider-declared credential secrets. A required-mode chain must
-// declare every secret of every credentialed vendor it names, so a missing
-// credential fails at build/validation time rather than during a live outage: a
-// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
-// exactly the failure class the multi-vendor chain exists to remove. Vendors
-// absent from this map (the deprecated `custom`/`decodo` values have no managed
-// adapter) impose no declaration requirement.
-const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
-	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
-	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
-};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
-const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
 const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"] as const;
+const VALID_OPERATION_CONNECTION_MODES = ["none", "optional", "required"] as const;
 const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"] as const;
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
@@ -583,6 +570,8 @@ export interface ProviderDeclaration {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
+	/** Provider business-logic target. Omit only while migrating a legacy provider. */
+	runtimeTarget?: ProviderRuntimeTarget;
 	/**
 	 * Optional deployment overrides, passed through verbatim onto the returned
 	 * provider definition. The SDK types this field but does not deep-validate
@@ -590,35 +579,36 @@ export interface ProviderDeclaration {
 	 * resolves omitted fields against the runtime deployment profiles.
 	 */
 	deployment?: ProviderDeploymentOverrides;
-	/** Declares that provider operations use the SDK HTTP client. */
-	http?: true;
+	/** Declares the HTTP capability binding. A bare object states use without configuration. */
+	http?: Record<string, never> | true;
+	/** Declares upstream host policy; this does not add a `ctx.allowedHosts` member. */
 	allowedHosts?: string[];
 	native?: NativeProviderConfig;
-	stealth?: {
-		profile: string;
-		platform: StealthPlatform;
-	};
+	stealth?: StealthProfileSelection;
+	/** Declares proxy policy; this is provider intent and does not add a `ctx.proxy` member. */
 	proxy?: ProviderProxyConfig;
 	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
 	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
-	/** Declares that provider operations issue and consume SDK choice tokens. */
-	choice?: true;
+	/** Declares the choice capability binding. A bare object states use without configuration. */
+	choice?: Record<string, never> | true;
 	reviewed?: ProviderReviewed;
 	access?: ProviderAccessConfig;
+	/** Declares secret requirements; this does not add a `ctx.secrets` member. */
 	secrets?: ProviderSecretDeclaration[];
-	/** Declares that provider operations read SDK-managed environment values. */
-	env?: true;
+	/** Declares the environment capability binding. A bare object states use without configuration. */
+	env?: Record<string, never> | true;
 	credential?: CredentialDeclaration;
+	/** Declares provider context metadata; this does not add a `ctx.context` member. */
 	context?: ContextDeclaration;
-	/** Declares that provider operations use SDK-managed persistent state. */
-	state?: true;
-	/** Declares that provider operations use the SDK provider cache. */
-	cache?: true;
-	/** Declares that provider operations access runtime-resolvable files. */
-	files?: true;
+	/** Declares the state capability binding. A bare object states use without configuration. */
+	state?: Record<string, never> | true;
+	/** Declares the cache capability binding. A bare object states use without configuration. */
+	cache?: Record<string, never> | true;
+	/** Declares the files capability binding. A bare object states use without configuration. */
+	files?: Record<string, never> | true;
 	meta: {
 		displayName: string;
 		displayNameKey?: string;
@@ -822,6 +812,18 @@ function validateProviderDeclarationShape(config: unknown): void {
 	assertRequiredField(config, "meta", String(config.id));
 	if (typeof config.runtime === "string")
 		assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+	if (config.runtimeTarget !== undefined && typeof config.runtimeTarget !== "string") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" has invalid runtimeTarget: expected "vanilla" or "engine"`,
+		);
+	}
+	if (typeof config.runtimeTarget === "string")
+		assertLiteralField(
+			config.runtimeTarget,
+			"runtimeTarget",
+			VALID_RUNTIME_TARGETS,
+			String(config.id),
+		);
 	if (config.native !== undefined && config.runtime === "browser") {
 		throw new ValidationError(
 			`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`,
@@ -830,6 +832,14 @@ function validateProviderDeclarationShape(config: unknown): void {
 			},
 		);
 	}
+	if (config.native !== undefined && config.runtimeTarget === "vanilla") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime target "vanilla"; native requires an engine-resident runtime`,
+			{
+				fix: 'Set runtimeTarget: "engine", or remove the native declaration.',
+			},
+		);
+	}
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -927,6 +937,23 @@ function validateProviderProxy(config: {
 	proxy?: ProviderProxyConfig;
 	secrets?: ProviderSecretDeclaration[];
 }): void {
+	for (const secret of config.secrets ?? []) {
+		if (isEngineOwnedTelemetryEnvName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned telemetry variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; trace export is configured only on the provider engine.`,
+				},
+			);
+		}
+		if (!isEngineOwnedProxyCredentialName(secret.name)) continue;
+		throw new ValidationError(
+			`Provider "${config.id}" cannot declare engine-owned proxy credential "${secret.name}"`,
+			{
+				fix: `Remove "${secret.name}" from provider secrets; configure it only on the provider engine.`,
+			},
+		);
+	}
 	const proxy = config.proxy;
 	if (proxy === undefined || typeof proxy === "boolean") {
 		return;
@@ -1042,44 +1069,12 @@ function validateProviderProxy(config: {
 			);
 		}
 	}
-	// Every credentialed vendor in a required-mode chain must declare its
-	// provider secret(s) so a missing credential fails at build/validation time,
-	// not during a live outage. This covers the fallback legs too (not just the
-	// first vendor): a declared-but-uncredentialed nodemaven fallback would leave
-	// the chain silently down to a single vendor, reintroducing the SPOF the chain
-	// removes.
 	const vendorChain =
 		proxy.providers && proxy.providers.length > 0
 			? proxy.providers
 			: proxy.provider
 				? [proxy.provider]
 				: [];
-	if (proxy.mode === "required") {
-		for (const vendor of vendorChain) {
-			const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
-			if (!requiredSecrets) continue;
-			for (const secretName of requiredSecrets) {
-				// Match the canonical runtime gate (assertRequiredSecretsPresent /
-				// listMissingRequiredSecrets), which enforces only `required === true`
-				// declarations. A declaration that omits `required` (defaulting to
-				// optional) is skipped at runtime, so accepting it here would pass
-				// validation while leaving the credential unenforced until proxy
-				// resolution during a live request — the fail-open gap this check exists
-				// to close.
-				const declared = config.secrets?.some(
-					(secret) => secret.name === secretName && secret.required === true,
-				);
-				if (!declared) {
-					throw new ValidationError(
-						`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`,
-						{
-							fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
-						},
-					);
-				}
-			}
-		}
-	}
 	// `decodo`/`custom` are deprecated vendor values (string-union members, so the
 	// @deprecated symbol gate can't catch them — warn at validation time instead).
 	const deprecatedVendors = vendorChain.filter(
@@ -1232,52 +1227,40 @@ function assertNonEmptyString(
 	}
 }
 
-function validateToolRouterMetadata(
+function validateOperationMetadata(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
 ): void {
 	for (const [operationName, operation] of Object.entries(operations)) {
-		const toolRouter = operation.toolRouter;
-		if (toolRouter === undefined) continue;
-		if (!toolRouter || typeof toolRouter !== "object") {
-			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter: must be an object.`,
-				{
-					fix: `Remove operations.${operationName}.toolRouter or provide MCP-safe metadata.`,
-				},
-			);
-		}
-		if (toolRouter.name !== undefined && !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
-			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.name: expected an MCP-safe name.`,
-				{
-					fix: `Use letters, numbers, and underscores only, starting with a letter, for example "${providerId.replace(/[^A-Za-z0-9]+/g, "_")}__${operationName.replace(/[^A-Za-z0-9]+/g, "_")}".`,
-				},
-			);
-		}
-		if (toolRouter.riskClass !== undefined) {
+		assertLiteralField(
+			operation.riskClass,
+			`operations.${operationName}.riskClass`,
+			VALID_OPERATION_RISK_CLASSES,
+			providerId,
+		);
+		if (operation.approval !== undefined) {
 			assertLiteralField(
-				toolRouter.riskClass,
-				`operations.${operationName}.toolRouter.riskClass`,
-				VALID_OPERATION_RISK_CLASSES,
+				operation.approval,
+				`operations.${operationName}.approval`,
+				VALID_OPERATION_APPROVAL_POLICIES,
 				providerId,
 			);
 		}
-		if (toolRouter.approval !== undefined) {
+		if (operation.connectionMode !== undefined) {
 			assertLiteralField(
-				toolRouter.approval,
-				`operations.${operationName}.toolRouter.approval`,
-				VALID_OPERATION_APPROVAL_POLICIES,
+				operation.connectionMode,
+				`operations.${operationName}.connectionMode`,
+				VALID_OPERATION_CONNECTION_MODES,
 				providerId,
 			);
 		}
 		if (
-			toolRouter.connectionExternalRefParam !== undefined &&
-			(typeof toolRouter.connectionExternalRefParam !== "string" ||
-				toolRouter.connectionExternalRefParam.trim().length === 0)
+			operation.connectionExternalRefParam !== undefined &&
+			(typeof operation.connectionExternalRefParam !== "string" ||
+				operation.connectionExternalRefParam.trim().length === 0)
 		) {
 			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.connectionExternalRefParam: must be a non-empty string.`,
+				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.connectionExternalRefParam: must be a non-empty string.`,
 				{
 					fix: `Use "externalRef" unless the operation has a documented public alias.`,
 				},
@@ -1350,16 +1333,14 @@ function validateOperationContracts(
 	}
 }
 
-function validateOperationAnnotations(
+function validateOperationTimeouts(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
 ): void {
 	for (const [operationName, operation] of Object.entries(operations)) {
-		const annotations = operation.annotations;
-		if (!annotations) continue;
-		const timeoutMs = annotations.timeoutMs;
+		const timeoutMs = operation.timeoutMs;
 		if (timeoutMs === undefined) continue;
-		const field = `operations.${operationName}.annotations.timeoutMs`;
+		const field = `operations.${operationName}.timeoutMs`;
 		if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs))
 			throw new ValidationError(
 				`Provider "${providerId}" has invalid ${field}: must be an integer number of milliseconds.`,
@@ -1440,12 +1421,12 @@ function validateOperationErrorCodes(
 	operations: Record<string, ProviderOperation>,
 ): void {
 	for (const [operationName, operation] of Object.entries(operations)) {
-		for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+		for (const [index, errorCode] of (operation.errorCodes ?? []).entries()) {
 			if (
 				errorCode.status !== undefined &&
 				!VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)
 			) {
-				const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+				const field = `operations.${operationName}.errorCodes[${index}].status`;
 				throw new ValidationError(
 					`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`,
 					{
@@ -2881,19 +2862,19 @@ function validateProviderDeployment(providerId: string, deployment: unknown): vo
 }
 
 /** The second authoring phase for a declaration established by defineProvider. */
-export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <
+export type ProviderBuilder<TConfig extends ProviderDeclaration> = <
 	TOperations extends Record<string, ProviderOperation>,
 >(
 	implementation: {
-		operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+		operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
 	},
 ) => Omit<ProviderDefinition, "operations"> & {
-	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+	operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
 };
 
 /** Extract the declaration-derived operation context from a provider builder. */
-export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration>
-	? ProviderContextFor<TDeclaration>
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TConfig>
+	? ProviderContext<TConfig>
 	: never;
 
 /** Annotate an operation while preserving the declaration-derived context. */
@@ -2907,22 +2888,22 @@ export type OperationDefinitionFor<
 export type ProviderDefinitionFor<TBuilder> = ProviderDefinition<ProviderContextOf<TBuilder>>;
 
 /** Establish a provider declaration before its operations are contextually typed. */
-export function defineProvider<const TDeclaration extends ProviderDeclaration>(
-	declaration: TDeclaration &
-		Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> &
-		AuthStartNoInputGuard<TDeclaration>,
-): ProviderBuilder<TDeclaration> {
+export function defineProvider<const TConfig extends ProviderDeclaration>(
+	declaration: TConfig &
+		Record<Exclude<keyof TConfig, keyof ProviderDeclaration>, never> &
+		AuthStartNoInputGuard<TConfig>,
+): ProviderBuilder<TConfig> {
 	validateProviderDeclaration(declaration);
 	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
 		implementation: {
-			operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+			operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
 		},
 	) =>
 		finalizeProvider({
 			...declaration,
 			...implementation,
-		} as ProviderConfig<TOperations, ProviderContextFor<TDeclaration>>);
-	return buildProvider as ProviderBuilder<TDeclaration>;
+		} as ProviderConfig<TOperations, ProviderContext<TConfig>>);
+	return buildProvider as ProviderBuilder<TConfig>;
 }
 
 function validateProviderDeclaration(config: ProviderDeclaration): void {
@@ -2985,12 +2966,12 @@ function finalizeProvider<
 			fix: "Add at least one operation to the operations object",
 		});
 	validateOperationIds(config.id, config.operations);
-	validateOperationAnnotations(config.id, config.operations);
+	validateOperationTimeouts(config.id, config.operations);
 	validateOperationObservability(config.id, config.operations);
 	validateOperationErrorCodes(config.id, config.operations);
 	validateOperationTransports(config.id, config.operations);
 	validateOperationContracts(config.id, config.operations);
-	validateToolRouterMetadata(config.id, config.operations);
+	validateOperationMetadata(config.id, config.operations);
 	const journeyCoveredOperations = validateHealthJourneys(
 		config.id,
 		config.operations,
@@ -3004,9 +2985,11 @@ function finalizeProvider<
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
+		runtimeTarget: config.runtimeTarget,
 		// Verbatim passthrough: deployment validation and profile resolution
 		// are owned by the APIFuse registry builder, not the SDK.
 		deployment: config.deployment,
+		http: config.http,
 		allowedHosts: config.allowedHosts,
 		native: config.native,
 		stealth: config.stealth,
@@ -3016,11 +2999,16 @@ function finalizeProvider<
 		resolver: config.resolver,
 		browser: config.browser,
 		auth: config.auth,
+		choice: config.choice,
 		reviewed: config.reviewed,
 		access: config.access,
 		secrets: config.secrets,
+		env: config.env,
 		credential: config.credential,
 		context: config.context,
+		state: config.state,
+		cache: config.cache,
+		files: config.files,
 		meta: config.meta,
 		operations,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field

package/src/dev.ts

@@ -1,9 +1,12 @@
 import { serve } from "./server/serve.js";
+import type { ProviderEngine } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 
 export interface DevServerOptions {
 	port?: number;
 	sessionDbPath?: string;
+	/** Override the default in-process engine attachment. */
+	engine?: ProviderEngine;
 }
 
 export function createDevServer(
@@ -14,7 +17,7 @@ export function createDevServer(
 
 	return {
 		start: () => {
-			void serve(provider, { port });
+			void serve(provider, { port, engine: options?.engine });
 			console.log(
 				`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`,
 			);