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

package/dist/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/dist/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/dist/config/loader.d.ts

@@ -58,6 +58,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 = "memory_hit" | "redis_hit" | "allocator" | "soft_stale_refresh" | "lock_wait" | "redis_error" | "redis_corrupt" | "disabled";
 export type SmartproxyAllocatorBodyClass = "network_error" | "http_error" | "empty" | "json_without_proxies" | "text_without_proxies" | "usable_proxy_endpoints";

package/dist/config/loader.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
 // extraction API (app_key → raw ip:port pool). It is NOT the company formerly
 // named Smartproxy (smartproxy.com), which rebranded to Decodo in 2025 and is
@@ -287,7 +287,7 @@ export async function resolveProxyConfigAsync(options = {}) {
         const nextVendor = chain[vendorIndex + 1];
         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,
@@ -313,6 +313,7 @@ export async function resolveProxyConfigAsync(options = {}) {
                 protocol,
                 poolIndex,
                 refreshEpoch,
+                credentials: options.engineCredentials,
             });
         }
         catch (error) {
@@ -497,10 +498,18 @@ function envDefaultProvider() {
     const raw = process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase();
     return raw ?? undefined;
 }
-function vendorHasCredentials(vendor) {
-    if (vendor === "nodemaven")
-        return hasNodemavenCredentials();
-    return Boolean(process.env[SMARTPROXY_APP_KEY_ENV]?.trim());
+function vendorHasCredentials(vendor, credentials) {
+    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) {
     return vendor === "nodemaven" ? "APIFUSE__PROXY__NODEMAVEN_USERNAME" : SMARTPROXY_APP_KEY_ENV;
@@ -1149,7 +1158,9 @@ function markSmartproxyCacheInvalidated(options = {}) {
         return undefined;
     }
     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, appKey, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);

package/dist/contract-types.d.ts

@@ -27,17 +27,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/dist/contract.js

@@ -48,17 +48,22 @@ export function digestProviderContract(snapshot) {
     return createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
 }
 function extractOperation(operationId, operation) {
+    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);
@@ -70,17 +75,23 @@ function extractOperation(operationId, operation) {
         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/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderRuntimeTarget, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthProfileSelection } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -46,6 +46,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
@@ -53,14 +55,13 @@ 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;
@@ -69,21 +70,23 @@ export interface ProviderDeclaration {
         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;
@@ -127,17 +130,17 @@ export declare function delayed(maxDelay: string): HealthScheduleRandomization;
 export declare function defineSmsOtpMatcher(config: Omit<SmsOtpMatcherDefinition, "extractOtp">): SmsOtpMatcherDefinition;
 export declare function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition;
 /** The second authoring phase for a declaration established by defineProvider. */
-export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <TOperations extends Record<string, ProviderOperation>>(implementation: {
-    operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+export type ProviderBuilder<TConfig extends ProviderDeclaration> = <TOperations extends Record<string, ProviderOperation>>(implementation: {
+    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> : never;
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TConfig> ? ProviderContext<TConfig> : never;
 /** Annotate an operation while preserving the declaration-derived context. */
 export type OperationDefinitionFor<TBuilder, TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> = OperationDefinition<TInput, TOutput, ProviderContextOf<TBuilder>>;
 /** Annotate a built provider while preserving the declaration-derived context. */
 export type ProviderDefinitionFor<TBuilder> = ProviderDefinition<ProviderContextOf<TBuilder>>;
 /** Establish a provider declaration before its operations are contextually typed. */
-export declare function defineProvider<const TDeclaration extends ProviderDeclaration>(declaration: TDeclaration & Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> & AuthStartNoInputGuard<TDeclaration>): ProviderBuilder<TDeclaration>;
+export declare function defineProvider<const TConfig extends ProviderDeclaration>(declaration: TConfig & Record<Exclude<keyof TConfig, keyof ProviderDeclaration>, never> & AuthStartNoInputGuard<TConfig>): ProviderBuilder<TConfig>;
 export {};

package/dist/define.js

@@ -2,6 +2,7 @@ import ms from "ms";
 import { validateFailClosedOperationDeclaration, validateFailClosedProviderDeclaration, } 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, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
@@ -10,6 +11,7 @@ import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD
 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"];
+const VALID_RUNTIME_TARGETS = ["vanilla", "engine"];
 const VALID_AUTH_MODES = [
     "none",
     "platform-managed",
@@ -71,24 +73,10 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray()([
     "akamai_sec_cpt",
     "akamai_sensor",
 ]);
-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 = {
-    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"];
 const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"];
+const VALID_OPERATION_CONNECTION_MODES = ["none", "optional", "required"];
 const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"];
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
@@ -562,11 +550,21 @@ function validateProviderDeclarationShape(config) {
     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"`, {
             fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
         });
     }
+    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));
@@ -634,6 +632,18 @@ function validateProviderImplementationShape(config) {
     assertRequiredField(configRecord, "operations", String(config.id));
 }
 function validateProviderProxy(config) {
+    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;
@@ -712,39 +722,11 @@ 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((vendor) => vendor === "decodo" || vendor === "custom");
@@ -839,31 +821,19 @@ function assertNonEmptyString(value, field, providerId, operationName) {
         throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${field}: must be a non-empty string.`, { fix: `Set ${field} to a non-empty customer-facing value.` });
     }
 }
-function validateToolRouterMetadata(providerId, operations) {
+function validateOperationMetadata(providerId, operations) {
     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, "_")}".`,
-            });
+        assertLiteralField(operation.riskClass, `operations.${operationName}.riskClass`, VALID_OPERATION_RISK_CLASSES, providerId);
+        if (operation.approval !== undefined) {
+            assertLiteralField(operation.approval, `operations.${operationName}.approval`, VALID_OPERATION_APPROVAL_POLICIES, providerId);
         }
-        if (toolRouter.riskClass !== undefined) {
-            assertLiteralField(toolRouter.riskClass, `operations.${operationName}.toolRouter.riskClass`, VALID_OPERATION_RISK_CLASSES, providerId);
+        if (operation.connectionMode !== undefined) {
+            assertLiteralField(operation.connectionMode, `operations.${operationName}.connectionMode`, VALID_OPERATION_CONNECTION_MODES, providerId);
         }
-        if (toolRouter.approval !== undefined) {
-            assertLiteralField(toolRouter.approval, `operations.${operationName}.toolRouter.approval`, VALID_OPERATION_APPROVAL_POLICIES, providerId);
-        }
-        if (toolRouter.connectionExternalRefParam !== undefined &&
-            (typeof toolRouter.connectionExternalRefParam !== "string" ||
-                toolRouter.connectionExternalRefParam.trim().length === 0)) {
-            throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.connectionExternalRefParam: must be a non-empty string.`, {
+        if (operation.connectionExternalRefParam !== undefined &&
+            (typeof operation.connectionExternalRefParam !== "string" ||
+                operation.connectionExternalRefParam.trim().length === 0)) {
+            throw new ValidationError(`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.`,
             });
         }
@@ -899,15 +869,12 @@ function validateOperationContracts(providerId, operations) {
         }
     }
 }
-function validateOperationAnnotations(providerId, operations) {
+function validateOperationTimeouts(providerId, operations) {
     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.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] (milliseconds).`,
@@ -957,10 +924,10 @@ function validateOperationObservability(providerId, operations) {
 }
 function validateOperationErrorCodes(providerId, operations) {
     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.`, {
                     fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
                 });
@@ -2022,12 +1989,12 @@ function finalizeProvider(config) {
             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, config.healthJourneys);
     validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
     validateOperationFixtures(config.id, operations);
@@ -2035,9 +2002,11 @@ function finalizeProvider(config) {
         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,
@@ -2047,11 +2016,16 @@ function finalizeProvider(config) {
         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/dist/dev.d.ts

@@ -1,7 +1,10 @@
+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 declare function createDevServer(provider: ProviderDefinition, options?: DevServerOptions): {
     start: () => void;

package/dist/dev.js

@@ -3,7 +3,7 @@ export function createDevServer(provider, options) {
     const port = options?.port ?? 3900;
     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}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -0,0 +1,78 @@
+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 declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
+export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
+/**
+ * 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 declare const ENGINE_OWNED_TELEMETRY_ENV_NAMES: readonly ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_HEADERS", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "OTEL_RESOURCE_ATTRIBUTES"];
+export declare function isEngineOwnedTelemetryEnvName(name: string): boolean;
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export declare function isEngineOwnedEnvName(name: string): boolean;
+/** Capture credentials in the engine host before constructing provider bindings. */
+export declare function readEngineProxyCredentials(environment?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>>;
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export declare function createProviderEnvironment(environment: Readonly<Record<string, string | undefined>>, declaredNames: readonly string[]): Readonly<Record<string, string>>;
+/**
+ * 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 declare const PROVIDER_CAPABILITY_KEYS: readonly ["env", "credential", "http", "files", "native", "cache", "state", "stealth", "browser", "auth", "ocr", "stt", "resolver", "choice"];
+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>;
+}
+/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+export declare function createInProcessProviderEngine(): ProviderEngine;