@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/src/types.ts

@@ -1,3 +1,5 @@
+import type ms from "ms";
+
 import type { infer as ZodInfer, ZodType } from "zod";
 
 /** Minimal Standard Schema v1 shape accepted by provider operations. */
@@ -45,6 +47,51 @@ export interface OperationInputExample {
 	rationale?: string;
 }
 
+export type OperationRiskClass =
+	| "read"
+	| "write"
+	| "destructive"
+	| "external-send";
+
+export type OperationApprovalPolicy = "never" | "risk-based" | "always";
+
+export interface OperationToolRouterMetadata {
+	/** Optional MCP-safe override. Defaults to providerId__operationId. */
+	name?: string;
+	/** Safety class exposed to Tool Router clients and approval policy. */
+	riskClass?: OperationRiskClass;
+	/** OpenAI remote-MCP approval hint. Defaults from riskClass. */
+	approval?: OperationApprovalPolicy;
+	/** Override connection requirement when provider auth + openWorld inference is insufficient. */
+	requiresConnection?: boolean;
+	/** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
+	connectionExternalRefParam?: string;
+}
+
+export type OperationSensitivePath = string;
+
+export interface OperationObservabilitySensitiveConfig {
+	/**
+	 * Additional dot paths to redact from captured invocation inputs. Use `*`
+	 * for array elements, for example `items.*.phone`.
+	 */
+	input?: readonly OperationSensitivePath[];
+	/**
+	 * Additional dot paths to redact from captured invocation outputs. Use `*`
+	 * for array elements, for example `items.*.paymentUrl`.
+	 */
+	output?: readonly OperationSensitivePath[];
+}
+
+export interface OperationObservabilityConfig {
+	/**
+	 * Complements schema-level `fields.*()` / `sensitive()` metadata for values
+	 * that are shape-dependent, provider-normalized, or otherwise easier to
+	 * express as stable public paths.
+	 */
+	sensitive?: OperationObservabilitySensitiveConfig;
+}
+
 export interface OperationAnnotations {
 	readOnly?: boolean;
 	destructive?: boolean;
@@ -80,9 +127,349 @@ export interface OperationAnnotations {
 export const OPERATION_TIMEOUT_MS_MIN = 1;
 export const OPERATION_TIMEOUT_MS_MAX = 60_000;
 
+export const STREAM_HEARTBEAT_MS_MIN = 1_000;
+export const STREAM_HEARTBEAT_MS_MAX = 60_000;
+export const STREAM_IDLE_TIMEOUT_MS_MIN = 1_000;
+export const STREAM_IDLE_TIMEOUT_MS_MAX = 300_000;
+export const STREAM_MAX_DURATION_MS_MIN = 1_000;
+export const STREAM_MAX_DURATION_MS_MAX = 1_800_000;
+export const STREAM_CHUNK_BYTES_MIN = 1;
+export const STREAM_CHUNK_BYTES_MAX = 1_048_576;
+
+export type OperationTransportKind =
+	| "json"
+	| "sse"
+	| "http-stream"
+	| "websocket";
+
+export interface OperationJsonTransport {
+	kind: "json";
+}
+
+export interface OperationSseTransport {
+	kind: "sse";
+	heartbeatMs?: number;
+	idleTimeoutMs?: number;
+	maxDurationMs?: number;
+	maxEventBytes?: number;
+	resumable?: false | "last-event-id";
+	events: Record<string, SchemaLike>;
+}
+
+export interface OperationHttpStreamTransport {
+	kind: "http-stream";
+	contentType?: string;
+	idleTimeoutMs?: number;
+	maxDurationMs?: number;
+	maxChunkBytes?: number;
+}
+
+export interface OperationWebSocketTransport {
+	kind: "websocket";
+	subprotocols?: readonly string[];
+	idleTimeoutMs?: number;
+	maxDurationMs?: number;
+	maxFrameBytes?: number;
+	/**
+	 * WebSocket Operation metadata is future-ready. Gateway dispatch remains
+	 * disabled until a gateway-managed session implementation is present.
+	 */
+	dispatch: "unsupported";
+}
+
+export type OperationTransport =
+	| OperationJsonTransport
+	| OperationSseTransport
+	| OperationHttpStreamTransport
+	| OperationWebSocketTransport;
+
+export const DEFAULT_OPERATION_TRANSPORT: OperationJsonTransport = {
+	kind: "json",
+};
+
 export interface OperationRelationships {
 	alternatives?: string[];
-	chainsWith?: string[];
+}
+
+export type Iso3166Alpha2CountryCode = Uppercase<string>;
+export type Bcp47Locale = string;
+export type ProviderLocale = Bcp47Locale;
+export type ProviderLocaleKey = string & {
+	readonly __brand: "ProviderLocaleKey";
+};
+export type ProviderLocaleKeyInput = ProviderLocaleKey | string;
+export type Iso8601Duration = string;
+export type Rfc3339Instant = string;
+export type IanaTimeZone = string;
+export type Iso4217CurrencyCode = Uppercase<string>;
+export type E164PhoneNumber = `+${string}`;
+
+export type SmsOrigin =
+	| {
+			/** Sender represented as an ITU-T E.164 phone number. */
+			kind: "e164";
+			value: E164PhoneNumber;
+			display?: string;
+	  }
+	| {
+			/** Country-local service sender, for example KR 1661-5270. */
+			kind: "nationalServiceCode";
+			country: Iso3166Alpha2CountryCode;
+			value: string;
+			display?: string;
+	  };
+
+export interface SmsOtpExtractionPattern {
+	/** RegExp or source string containing exactly one usable OTP capture. */
+	pattern: RegExp | string;
+	/** Named capture key or one-based numeric capture index. Defaults to first capture. */
+	capture?: string | number;
+}
+
+export interface SmsOtpMatcherDefinition {
+	id: string;
+	country: Iso3166Alpha2CountryCode;
+	locale?: Bcp47Locale;
+	phoneNumber?: E164PhoneNumber;
+	origins: readonly [SmsOrigin, ...SmsOrigin[]];
+	code: SmsOtpExtractionPattern;
+	maxAge: Iso8601Duration;
+	waitTimeout: Iso8601Duration;
+	clockSkew?: Iso8601Duration;
+	/** Runtime/fixture helper. Not serialized into generated registry artifacts. */
+	extractOtp(body: string): string | null;
+}
+
+export type SttTranscribeMode = "general" | "otp";
+export type SttPromptPolicy = "none" | "default-hint" | "custom-hint";
+export type SttUnsupportedOptionPolicy = "warn" | "error";
+export type ProviderSttMode = "optional" | "required";
+
+export interface ProviderSttConfig {
+	mode: ProviderSttMode;
+}
+
+export type SttAudioInput = {
+	kind: "base64";
+	data: string;
+	mediaType?: string;
+	durationMs?: number;
+};
+
+export interface SttVerificationCodeOptions {
+	locale?: Bcp47Locale;
+	codeLengths?: number | readonly number[] | { min: number; max: number };
+}
+
+export interface SttTranscribeRequest {
+	audio: SttAudioInput;
+	language?: Bcp47Locale;
+	mode?: SttTranscribeMode;
+	promptPolicy?: SttPromptPolicy;
+	initialPrompt?: string;
+	unsupportedOptionPolicy?: SttUnsupportedOptionPolicy;
+	verificationCode?: SttVerificationCodeOptions;
+	timeoutMs?: number;
+	maxAudioBytes?: number;
+}
+
+export interface SttSegment {
+	text: string;
+	startMs?: number;
+	endMs?: number;
+	confidence?: number;
+}
+
+export interface SttUsage {
+	audioDurationMs?: number;
+	audioBytes?: number;
+	billableUnits?: number;
+}
+
+export interface SttWarning {
+	code: "UNSUPPORTED_STT_OPTION" | "PROMPT_IGNORED" | "LOCALE_PARTIAL";
+	message: string;
+}
+
+export interface SttTranscript {
+	text: string;
+	language?: Bcp47Locale;
+	durationMs?: number;
+	segments?: readonly SttSegment[];
+	usage?: SttUsage;
+	warnings?: readonly SttWarning[];
+	verificationCode?: VerificationCodeExtractionResult;
+}
+
+export type VerificationCodeCandidateSource =
+	| "digits"
+	| "spoken_words"
+	| "mixed";
+
+export interface VerificationCodeCandidate {
+	code: string;
+	source: VerificationCodeCandidateSource;
+	startIndex?: number;
+	endIndex?: number;
+}
+
+export interface VerificationCodeExtractionResult {
+	code: string;
+	candidates: readonly VerificationCodeCandidate[];
+	normalizedText: string;
+}
+
+export interface SttContext {
+	transcribe(request: SttTranscribeRequest): Promise<SttTranscript>;
+	extractVerificationCode(
+		text: string,
+		options?: SttVerificationCodeOptions,
+	): VerificationCodeExtractionResult;
+}
+
+export interface HealthJourneySchedule {
+	kind: "interval";
+	/** ISO 8601 duration, for example PT8H. */
+	interval: Iso8601Duration;
+	jitter?: Iso8601Duration;
+}
+
+export interface HealthJourneyStep {
+	id: string;
+	description?: string;
+	operationId?: string;
+	usesSmsMatcher?: string;
+	coversOperations?: readonly string[];
+	safeBoundary?: "paymentWebviewUrl" | "paymentUrl" | "none";
+	kind?: "operation" | "smsOtp" | "assertion" | "journal";
+}
+
+export interface HealthJourneyGatewayContext {
+	connect?(options?: {
+		providerId?: string;
+		externalRef?: string;
+		authMode?: "credentials" | "oauth2";
+		input?: Record<string, unknown>;
+		metadata?: Record<string, unknown>;
+	}): Promise<{ connectionId: string; rowVersion: number }>;
+	disconnect?(connection: {
+		connectionId: string;
+		rowVersion: number;
+	}): Promise<void>;
+	execute(
+		providerId: string,
+		operationId: string,
+		input: unknown,
+		options?: {
+			connectionId?: string;
+			requestId?: string;
+			/**
+			 * Set false when the journey will record the semantic operation
+			 * outcome itself through `ctx.event.operation()`. Transport success
+			 * must not become a competing public health sample in that case.
+			 */
+			recordOperationEvent?: boolean;
+		},
+	): Promise<{
+		data: unknown;
+		status: number;
+		duration: number;
+		meta?: Record<string, unknown>;
+	}>;
+}
+
+export interface SmsPhoneIdentity {
+	id: string;
+	country: Iso3166Alpha2CountryCode | string;
+	e164: E164PhoneNumber | string;
+	nationalNumber: string;
+	displayName?: string;
+}
+
+export interface HealthJourneySmsContext {
+	resolvePhone(params?: { matcherId?: string }): Promise<SmsPhoneIdentity>;
+	waitForOtp(params: {
+		matcherId: string;
+		attemptId: string;
+		phoneId?: string;
+		phoneNumber?: string;
+		signal?: AbortSignal;
+	}): Promise<{ code: string; messageId: string; receivedAt: string }>;
+}
+
+export interface HealthJourneyJournalContext {
+	sideEffect<T>(params: {
+		stepId: string;
+		kind: string;
+		idempotencyKey: string;
+		run: () => Promise<T>;
+	}): Promise<T>;
+}
+
+export interface HealthJourneyEventContext {
+	/**
+	 * Record an operation-level health outcome that was proven by the journey but
+	 * not emitted by a direct `ctx.gateway.execute()` call, such as a recovery or
+	 * manual-review assertion. This is intentionally narrow; it is not a generic
+	 * event bus.
+	 */
+	operation(params: {
+		operationId: string;
+		status: "ok" | "degraded" | "down" | "unknown" | "not_reached";
+		stepId?: string;
+		label?: string;
+		error?: string;
+		latencyMs?: number;
+		statusCode?: number;
+		metadata?: Record<string, unknown>;
+	}): Promise<void>;
+}
+
+export interface HealthJourneyRunContext {
+	attemptId: string;
+	providerId: string;
+	journeyId: string;
+	gateway: HealthJourneyGatewayContext;
+	sms: HealthJourneySmsContext;
+	journal: HealthJourneyJournalContext;
+	state: ProviderRuntimeState;
+	event: HealthJourneyEventContext;
+	signal: AbortSignal;
+	secrets: Record<string, string | undefined>;
+}
+
+export type HealthJourneyManualTriggerPolicy =
+	| { enabled: false; reason?: string }
+	| {
+			enabled: true;
+			requiresAcknowledgement: boolean;
+			risk: "read_only" | "writes_external_state" | "sms_or_payment";
+			/** ISO 8601 duration. Minimum time between manual executions. */
+			minManualInterval: Iso8601Duration;
+			publicRationale: string;
+	  };
+
+export interface HealthJourneyRunResult {
+	status?: "ok" | "degraded" | "down" | "unknown";
+	label?: string;
+	metadata?: Record<string, unknown>;
+}
+
+export interface HealthJourneyDefinition {
+	id: string;
+	title?: string;
+	description?: string;
+	schedule: HealthJourneySchedule;
+	coversOperations: readonly [string, ...string[]];
+	timeout?: Iso8601Duration;
+	cooldown?: Iso8601Duration;
+	smsMatchers?: readonly SmsOtpMatcherDefinition[];
+	requiredSecrets?: readonly string[];
+	manualTrigger?: HealthJourneyManualTriggerPolicy;
+	steps: readonly [HealthJourneyStep, ...HealthJourneyStep[]];
+	run?: (
+		ctx: HealthJourneyRunContext,
+	) => Promise<HealthJourneyRunResult | undefined>;
 }
 
 /**
@@ -96,9 +483,14 @@ export interface OperationRelationships {
  * See `openspec/changes/enforce-sdk-operation-health-suite/design.md` §D1.
  */
 
-/** Polling intervals supported by the health-monitor runtime. */
-export type ProbeInterval = "30s" | "1m" | "3m" | "5m" | "15m" | "30m" | "1h";
+/** Polling interval duration accepted by the health-monitor runtime. */
+export type ProbeInterval = ms.StringValue;
 
+/**
+ * Common probe interval examples retained for discoverability/backwards
+ * compatibility. This list is not exhaustive; any positive `ms`-style duration
+ * string accepted by `@types/ms` (for example `2m`, `8h`, or `1 day`) is valid.
+ */
 export const PROBE_INTERVALS: readonly ProbeInterval[] = [
 	"30s",
 	"1m",
@@ -107,8 +499,16 @@ export const PROBE_INTERVALS: readonly ProbeInterval[] = [
 	"15m",
 	"30m",
 	"1h",
+	"2h",
+	"8h",
+	"24h",
 ] as const;
 
+export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
+export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+
 /**
  * Context passed to a `HealthCheckCase.assertions` lambda.
  * `data` is typed against the operation's declared output schema (TOutput).
@@ -120,6 +520,28 @@ export interface HealthCheckAssertionContext<TOutput = unknown> {
 	readonly status: number;
 	/** Wall-clock duration of the operation invocation, in milliseconds. */
 	readonly durationMs: number;
+	/** Optional provider response metadata such as cache hit/stale flags. */
+	readonly meta?: Record<string, unknown>;
+}
+
+export interface HealthCheckInputPreparationContext<TInput = unknown> {
+	readonly providerId: string;
+	readonly operationId: string;
+	readonly input: TInput;
+	readonly connectionId?: string;
+	readonly gateway: {
+		execute: (
+			providerId: string,
+			operationId: string,
+			input: unknown,
+			options?: { connectionId?: string },
+		) => Promise<{
+			status: number;
+			duration: number;
+			data: unknown;
+			meta?: Record<string, unknown>;
+		}>;
+	};
 }
 
 /**
@@ -148,6 +570,14 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 	description?: string;
 	/** Input passed to the operation handler for this case. */
 	input: TInput;
+	/**
+	 * Optional runtime input preparation hook for volatile probes. Use this when
+	 * the durable probe input must be derived from a live read-only operation
+	 * immediately before the checked operation executes.
+	 */
+	prepareInput?: (
+		ctx: HealthCheckInputPreparationContext<TInput>,
+	) => TInput | Promise<TInput>;
 	/**
 	 * Assertion executed against the operation's response and timing.
 	 *
@@ -167,6 +597,8 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 		| Promise<HealthCheckCaseResult>;
 	/** Override per-case degradation threshold (ms); falls back to the suite default. */
 	degradedThresholdMs?: number;
+	/** Override per-case timeout in milliseconds; falls back to the suite/provider/runtime default. */
+	timeoutMs?: number;
 	/** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
 	expectedStatus?: "ok" | "degraded";
 	/** Runtime gate (env-driven); if returns false the case is skipped & logged. */
@@ -182,6 +614,8 @@ export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
 	interval: ProbeInterval;
 	/** Per-case timeout in milliseconds. Default: 30000. */
 	timeoutMs?: number;
+	/** Default degradation threshold for cases in this suite. Default: runtime threshold. */
+	degradedThresholdMs?: number;
 	/** Non-empty list of cases. Empty arrays are rejected at definition time. */
 	cases: [
 		HealthCheckCase<TInput, TOutput>,
@@ -217,18 +651,51 @@ export interface HealthCheckUnsupported {
  */
 export interface ProviderHealthMonitorConfig {
 	/**
-	 * Env-secret key names (e.g., "HEALTH_MONITOR_CATCHTABLE_PHONE") the
+	 * Provider-wide default probe timeout in milliseconds. Individual
+	 * `healthCheck.timeoutMs` and `healthCheck.cases[].timeoutMs` values take
+	 * precedence. Defaults to the monitor runtime default.
+	 */
+	defaultProbeTimeoutMs?: number;
+	/**
+	 * Provider-wide default latency threshold in milliseconds before an
+	 * otherwise successful probe is marked degraded. Suite/case thresholds take
+	 * precedence. Defaults to the monitor runtime default.
+	 */
+	defaultDegradedThresholdMs?: number;
+	/**
+	 * Env-secret key names (e.g., "APIFUSE__HEALTH_MONITOR__CATCHTABLE_PHONE") the
 	 * synthetic-monitor runtime needs to execute probes that declare
 	 * `requiresConnection: true`.
 	 */
 	requiredSecrets?: string[];
+	/**
+	 * Mapping from provider auth ceremony input fields to runtime env-secret
+	 * names. The health-monitor uses this to create a fresh connection for
+	 * `requiresConnection: true` probes, then disconnects after execution.
+	 */
+	credentialInputs?: Record<string, string>;
+	/**
+	 * Runtime probe overrides keyed by generated registry probe id. Use this for
+	 * operation health checks that need a runtime-specific interval or threshold
+	 * without changing the provider-authored default suite.
+	 */
+	probeOverrides?: Record<string, HealthMonitorProbeOverride>;
 	/**
 	 * Override the default service account ID for this provider's probes.
-	 * Defaults to the runtime's `APIFUSE_SERVICE_ACCOUNT_ID` env var.
+	 * Defaults to the runtime's `APIFUSE__HEALTH_MONITOR__SERVICE_ACCOUNT_ID` env var.
 	 */
 	serviceAccount?: string;
 }
 
+export interface HealthMonitorProbeOverride {
+	/** Optional runtime interval override as a positive `ms`-style duration string. */
+	interval?: ProbeInterval;
+	/** Optional timeout override for generated registry probes. */
+	timeoutMs?: number;
+	/** Optional degraded threshold override for generated registry probes. */
+	degradedThresholdMs?: number;
+}
+
 export interface OperationErrorCode {
 	code: string;
 	status?: number;
@@ -237,10 +704,11 @@ export interface OperationErrorCode {
 }
 
 export interface OperationDocMeta {
-	title?: string;
-	description?: string;
-	summary?: string;
-	normalizationNotes?: string[];
+	titleKey?: ProviderLocaleKeyInput;
+	descriptionKey?: ProviderLocaleKeyInput;
+	summaryKey?: ProviderLocaleKeyInput;
+	markdownKey?: ProviderLocaleKeyInput;
+	normalizationNotesKeys?: ProviderLocaleKeyInput[];
 	requestExample?: Record<string, unknown>;
 	responseExample?: unknown;
 	errorCodes?: OperationErrorCode[];
@@ -249,12 +717,12 @@ export interface OperationDocMeta {
 export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
 
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
-
 export interface BrowserOptions {
 	headless?: boolean;
 	stealth?: boolean;
 	proxy?: string;
 	engine?: BrowserEngine;
+	requireCdpPool?: boolean;
 }
 
 export interface StealthProfile {
@@ -275,36 +743,259 @@ export type ConnectionMode = AuthMode;
 
 export type ProviderReviewed = "first-party" | "community" | "staging";
 
+export type ProviderAccessVisibility = "public" | "early_access";
+
+export type ProviderProxyMode = "disabled" | "optional" | "required";
+
+export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+
+export type ProviderProxySessionAffinity =
+	| "request"
+	| "operation"
+	| "auth-flow"
+	| "connection";
+
+export interface ProviderProxyPolicy {
+	/**
+	 * Provider intent only. Transport details such as raw CONNECT, origin
+	 * certificate verification, and vendor allocator endpoints are SDK-owned.
+	 */
+	mode: ProviderProxyMode;
+	provider?: ProviderProxyProvider;
+	geo?: {
+		/** ISO 3166-1 alpha-2 country code, for example KR or US. */
+		country?: Iso3166Alpha2CountryCode;
+		subdivision?: string;
+		city?: string;
+	};
+	session?: {
+		affinity?: ProviderProxySessionAffinity;
+		lifetimeMinutes?: number;
+		poolSize?: number;
+	};
+}
+
+export type ProviderProxyConfig = boolean | ProviderProxyPolicy;
+
+export interface ProviderAccessConfig {
+	/**
+	 * Provider-level rollout visibility.
+	 *
+	 * - `public`: visible in public docs/catalog/OpenAPI and callable through
+	 *   the existing provider policy stack.
+	 * - `early_access`: hidden from public discovery and callable only when the
+	 *   active customer organization has a provider-level access grant.
+	 *
+	 * This is intentionally provider-level only. It does not alter auth mode,
+	 * operation schemas, health-check authoring, `openWorld`, or Connection
+	 * requirements.
+	 */
+	visibility?: ProviderAccessVisibility;
+}
+
+export type ProviderLogoSource = "asset" | "monogram" | "none";
+
+export type ProviderLogoProfile =
+	| {
+			source: "asset";
+			path: string;
+			/**
+			 * Absolute, customer-renderable URL emitted by discovery projections.
+			 * Provider source definitions may omit this and let the registry projection
+			 * derive it from the committed public asset path.
+			 */
+			url?: string;
+			background?: string;
+	  }
+	| {
+			source: "monogram" | "none";
+			background?: string;
+			fallbackReason: string;
+	  };
+
+export type ProviderPublicConnectionMode =
+	| "apifuse_managed"
+	| "workspace_enabled"
+	| "user_connected"
+	| "no_connection_required";
+
+export type ProviderSupportLevel = "stable" | "beta" | "experimental";
+
+export interface ProviderPublicProfile {
+	displayNameKey?: ProviderLocaleKeyInput;
+	shortDescriptionKey?: ProviderLocaleKeyInput;
+	longDescriptionKey?: ProviderLocaleKeyInput;
+	logo?: ProviderLogoProfile;
+	category?: string;
+	tags?: readonly string[];
+	capabilityKeys?: readonly ProviderLocaleKeyInput[];
+	examplePromptKeys?: readonly ProviderLocaleKeyInput[];
+	setupSummaryKey?: ProviderLocaleKeyInput;
+	connectionMode?: ProviderPublicConnectionMode;
+	requirementKeys?: readonly ProviderLocaleKeyInput[];
+	limitationKeys?: readonly ProviderLocaleKeyInput[];
+	availability?: {
+		regions?: readonly string[];
+		supportLevel?: ProviderSupportLevel;
+	};
+	/**
+	 * Brand primary color as a 6-digit hex string (e.g. "#1a73e8").
+	 * Single source of truth for all provider-specific color expressions
+	 * (mood wash, monogram fallback, icon tint). The UI derives subtle washes
+	 * via color-mix; provider definitions do not control mood percentages.
+	 */
+	primaryColor?: string;
+}
+
 export interface ProviderMeta {
 	displayName: string;
-	description?: string;
+	displayNameKey?: ProviderLocaleKeyInput;
+	descriptionKey: ProviderLocaleKeyInput;
 	category: string;
-	tags?: string[];
+	tags?: readonly string[];
 	icon?: string;
-	docTitle?: string;
-	docDescription?: string;
-	docSummary?: string;
-	normalizationNotes?: string[];
+	docTitleKey?: ProviderLocaleKeyInput;
+	docDescriptionKey?: ProviderLocaleKeyInput;
+	docSummaryKey?: ProviderLocaleKeyInput;
+	docMarkdownKey?: ProviderLocaleKeyInput;
+	normalizationNotesKeys?: readonly ProviderLocaleKeyInput[];
 	environment?: "staging";
 	purpose?: string;
+	purposeKey?: ProviderLocaleKeyInput;
+	publicProfile?: ProviderPublicProfile;
+	contract?: {
+		publicSchemaFieldNames?: "normalized";
+	};
+}
+
+export type RequestParamPrimitive =
+	| string
+	| number
+	| boolean
+	| null
+	| undefined;
+export type RequestParamValue =
+	| RequestParamPrimitive
+	| readonly RequestParamPrimitive[];
+export type RequestParams = Record<string, RequestParamValue>;
+
+export const HttpRetryPreset = {
+	Off: "off",
+	TransportTransient: "transport_transient",
+	SafeRead: "safe_read",
+	AggressiveRead: "aggressive_read",
+	RateLimitAware: "rate_limit_aware",
+} as const;
+export type HttpRetryPreset =
+	(typeof HttpRetryPreset)[keyof typeof HttpRetryPreset];
+
+export const HttpRetryJitter = {
+	None: "none",
+	Full: "full",
+	Equal: "equal",
+} as const;
+export type HttpRetryJitter =
+	(typeof HttpRetryJitter)[keyof typeof HttpRetryJitter];
+
+export const HttpRetryDelayStrategy = {
+	Fixed: "fixed",
+	Exponential: "exponential",
+} as const;
+export type HttpRetryDelayStrategy =
+	(typeof HttpRetryDelayStrategy)[keyof typeof HttpRetryDelayStrategy];
+
+export const HttpRetryAfterPolicy = {
+	Ignore: "ignore",
+	/** Honor Retry-After up to maxDelayMs. */
+	Respect: "respect",
+	/** Honor Retry-After but also cap it to the SDK-computed backoff delay. */
+	Cap: "cap",
+} as const;
+export type HttpRetryAfterPolicy =
+	(typeof HttpRetryAfterPolicy)[keyof typeof HttpRetryAfterPolicy];
+
+export const HttpRetryUnsafeMethodPolicy = {
+	Reject: "reject",
+	AllowExplicitUnsafe: "allow_explicit_unsafe",
+} as const;
+export type HttpRetryUnsafeMethodPolicy =
+	(typeof HttpRetryUnsafeMethodPolicy)[keyof typeof HttpRetryUnsafeMethodPolicy];
+
+export interface HttpRetryOptions {
+	preset?: HttpRetryPreset;
+	/** Total logical ctx.http attempts, including the first attempt. */
+	attempts?: number;
+	methods?: readonly HttpMethod[];
+	statusCodes?: readonly number[];
+	errorCodes?: readonly string[];
+	delayStrategy?: HttpRetryDelayStrategy;
+	baseDelayMs?: number;
+	maxDelayMs?: number;
+	jitter?: HttpRetryJitter;
+	retryAfter?: HttpRetryAfterPolicy;
+	unsafeMethodPolicy?: HttpRetryUnsafeMethodPolicy;
+}
+
+export interface HttpRetrySummary {
+	attempts: number;
+	retries: number;
+	preset?: HttpRetryPreset;
+	transport: "native";
+	lastErrorCode?: string;
+	lastStatus?: number;
 }
 
 export interface RequestOptions {
 	headers?: Record<string, string>;
-	params?: Record<string, string>;
+	params?: RequestParams;
 	proxy?: string;
 	timeout?: number;
+	/**
+	 * Defaults to true. Set to false when callers need to inspect upstream
+	 * non-2xx bodies themselves instead of converting them to TransportError.
+	 */
+	throwOnHttpError?: boolean;
+	retry?: boolean | HttpRetryPreset | HttpRetryOptions;
 }
 
-export interface TlsFetchOptions extends RequestOptions {
-	method?: string;
+export type HttpMethod =
+	| "HEAD"
+	| "head"
+	| "GET"
+	| "get"
+	| "POST"
+	| "post"
+	| "PUT"
+	| "put"
+	| "DELETE"
+	| "delete"
+	| "OPTIONS"
+	| "options"
+	| "TRACE"
+	| "trace"
+	| "PATCH"
+	| "patch";
+
+export interface StealthFetchOptions extends RequestOptions {
+	method?: HttpMethod;
 	body?: string | Buffer;
+	/**
+	 * Offsets policy-managed proxy pool selection for caller-managed retries.
+	 * Use when a request receives an upstream challenge page rather than a
+	 * transport error, so the next logical retry does not restart at the same
+	 * operation-affinity proxy.
+	 */
+	proxyAttemptOffset?: number;
+	/** Override the configured browser-like stealth profile for this request. */
 	profile?: string;
-	tls?: {
-		ja3?: string;
-		h2?: Record<string, unknown>;
+	/**
+	 * Stealth transport certificate controls. Use only for proxy products that
+	 * terminate CONNECT with a private CA instead of tunneling the origin
+	 * certificate chain.
+	 */
+	stealth?: {
+		insecureSkipVerify?: boolean;
 	};
-	headerOrder?: string[];
 }
 
 export interface CookieJar {
@@ -314,7 +1005,7 @@ export interface CookieJar {
 	find?(predicate: (cookie: string) => boolean): string | undefined;
 }
 
-export interface DeclarativeTlsResponse {
+export interface DeclarativeStealthResponse {
 	status: number;
 	ok: boolean;
 	headers: Record<string, string>;
@@ -324,16 +1015,19 @@ export interface DeclarativeTlsResponse {
 	tlsInfo?: { protocol?: string; cipher?: string; [key: string]: unknown };
 	cookies: CookieJar;
 	json<T>(): Promise<T>;
+	arrayBuffer(): Promise<ArrayBuffer>;
+	bytes(): Promise<Uint8Array>;
 }
 
-export type TlsResponse = DeclarativeTlsResponse;
+export type StealthResponse = DeclarativeStealthResponse;
 
 export type RequestWithMethodOptions = RequestOptions & {
 	method?: string;
+	body?: unknown;
 };
 
-export interface TlsSession {
-	fetch(url: string, options?: TlsFetchOptions): Promise<TlsResponse>;
+export interface StealthSession {
+	fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
 	close(): void;
 }
 
@@ -343,6 +1037,9 @@ export interface ApiFuseResponse<T> {
 		requestId: string;
 		duration: number;
 		cached?: boolean;
+		stale?: boolean;
+		cache?: ProviderCacheResponseMeta;
+		retry?: HttpRetrySummary;
 	};
 }
 
@@ -355,6 +1052,37 @@ export interface HttpResponse<T = unknown> {
 	text(): Promise<string>;
 }
 
+export interface HttpStreamResponse {
+	status: number;
+	ok: boolean;
+	headers: Record<string, string>;
+	body: ReadableStream<Uint8Array>;
+	bytes(): AsyncIterable<Uint8Array>;
+	textChunks(): AsyncIterable<string>;
+	lines(): AsyncIterable<string>;
+}
+
+export interface SseMessage {
+	event: string;
+	data: string;
+	id?: string;
+	retry?: number;
+	json<T = unknown>(): T;
+}
+
+export interface ProviderStreamEvent<TData = unknown> {
+	event: string;
+	data: TData;
+	id?: string;
+	retry?: number;
+}
+
+export type OperationHandlerResult<TOutput> =
+	| TOutput
+	| Response
+	| ReadableStream<Uint8Array>
+	| AsyncIterable<ProviderStreamEvent>;
+
 export interface HttpClient {
 	request(url: string, opts?: RequestWithMethodOptions): Promise<HttpResponse>;
 	get(url: string, options?: RequestOptions): Promise<HttpResponse>;
@@ -369,18 +1097,142 @@ export interface HttpClient {
 		options?: RequestOptions,
 	): Promise<HttpResponse>;
 	delete(url: string, options?: RequestOptions): Promise<HttpResponse>;
+	stream(
+		url: string,
+		options?: RequestWithMethodOptions,
+	): Promise<HttpStreamResponse>;
+	sse(
+		url: string,
+		options?: RequestWithMethodOptions,
+	): Promise<AsyncIterable<SseMessage>>;
 }
 
-export interface TlsClient {
-	fetch(url: string, options?: TlsFetchOptions): Promise<TlsResponse>;
-	createSession(opts?: { profile?: string }): TlsSession;
+export interface ProviderCacheKeyOptions {
+	/**
+	 * Additional field names to omit from stable key material. The SDK always
+	 * omits known secret-bearing names such as serviceKey, authorization,
+	 * cookie, token, password, and secret.
+	 */
+	redactFields?: string[];
+}
+
+export interface ProviderCacheGetOrSetOptions {
+	/** Freshness TTL. A fresh hit returns without calling the loader. */
+	ttlMs: number;
+	/**
+	 * Optional stale window after ttlMs. If the loader fails while the entry is
+	 * still inside this window, stale data is returned and marked stale.
+	 */
+	staleIfErrorMs?: number;
+	/** Optional jitter applied to writes to avoid synchronized expiry. */
+	jitterPct?: number;
+}
+
+export interface ProviderCacheLookupMeta {
+	key: string;
+	hit: boolean;
+	stale: boolean;
+	ageMs?: number;
+	source: "redis" | "memory" | "loader";
+}
+
+export interface ProviderCacheResult<T> {
+	value: T;
+	meta: ProviderCacheLookupMeta;
+}
+
+export interface ProviderCacheResponseMeta {
+	hit: boolean;
+	stale: boolean;
+	keys: string[];
+	source?: "redis" | "memory" | "loader" | "mixed";
+}
+
+export interface ProviderCache {
+	key(
+		namespace: string,
+		parts: unknown,
+		options?: ProviderCacheKeyOptions,
+	): string;
+	get<T = unknown>(key: string): Promise<ProviderCacheResult<T> | null>;
+	set<T = unknown>(
+		key: string,
+		value: T,
+		options: ProviderCacheGetOrSetOptions,
+	): Promise<void>;
+	delete(key: string): Promise<void>;
+	getOrSet<T = unknown>(
+		key: string,
+		loader: () => Promise<T>,
+		options: ProviderCacheGetOrSetOptions,
+	): Promise<ProviderCacheResult<T>>;
+	responseMeta(): ProviderCacheResponseMeta | undefined;
+}
+
+export interface StealthClient {
+	fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+	createSession(opts?: { profile?: string }): StealthSession;
+	close?(): void;
 }
 
 export interface BrowserClient {
 	readonly engine: BrowserEngine;
-	newPage(): Promise<unknown>;
+	close?(): Promise<void>;
+	newPage(): Promise<BrowserPage>;
+	rawPage(): Promise<BrowserPage>;
+	withIsolatedContext<T>(
+		handler: (page: BrowserPage) => Promise<T>,
+	): Promise<T>;
+	solveChallenge(
+		request: BrowserChallengeRequest,
+	): Promise<BrowserChallengeResult>;
+}
+
+export interface BrowserLocator {
+	click(): Promise<void>;
+	fill(text: string): Promise<void>;
+	textContent(): Promise<string | null>;
+	waitFor(options?: { timeout?: number }): Promise<void>;
 }
 
+export interface BrowserFrame {
+	id: string;
+	name?: string;
+	parentId?: string;
+	url(): Promise<string>;
+	title(): Promise<string>;
+	content(): Promise<string>;
+	evaluate<T>(fn: string | (() => T)): Promise<T>;
+	locator(selector: string): BrowserLocator;
+}
+
+export interface BrowserPage extends BrowserFrame {
+	close(): Promise<void>;
+	fill(selector: string, text: string): Promise<void>;
+	goto(url: string): Promise<void>;
+	pageId?: string;
+	screenshot(options?: { fullPage?: boolean }): Promise<Buffer>;
+	click(selector: string): Promise<void>;
+	type(selector: string, text: string): Promise<void>;
+	waitForSelector(
+		selector: string,
+		options?: { timeout?: number },
+	): Promise<void>;
+	frames(): Promise<BrowserFrame[]>;
+}
+
+export type BrowserChallengeRequest = {
+	type: "recaptcha";
+	siteKey?: string;
+	timeout?: number;
+};
+
+export type BrowserChallengeResult = {
+	type: BrowserChallengeRequest["type"];
+	solved: boolean;
+	frameUrl?: string;
+};
+
 export type TraceAttributeValue = string | number | boolean;
 
 export interface TraceSpan {
@@ -436,6 +1288,107 @@ export interface ProviderRequestContext {
 	headers: Record<string, string>;
 }
 
+export interface ProviderChoiceBindingOptions {
+	connection?: boolean;
+	credentialKeys?: readonly string[];
+}
+
+export type ProviderChoiceStorageOptions =
+	| {
+			readonly mode: "inline";
+	  }
+	| {
+			readonly mode: "server";
+			readonly namespace: string;
+			readonly state?: ProviderRuntimeState;
+			readonly ttl?: ProviderStateDurationString;
+			readonly maxEntries: number;
+			readonly maxValueBytes: number;
+			readonly unavailable?: "reject";
+	  }
+	| {
+			readonly mode: "auto";
+			readonly namespace: string;
+			readonly state?: ProviderRuntimeState;
+			readonly ttl?: ProviderStateDurationString;
+			readonly maxInlineBytes: number;
+			readonly maxEntries: number;
+			readonly maxValueBytes: number;
+			readonly unavailable?: "reject";
+	  };
+
+export interface ProviderChoiceIssueOptions<
+	TPayload extends Record<string, unknown>,
+> {
+	prefix: string;
+	purpose: string;
+	payload: TPayload;
+	ttlMs: number;
+	nowMs?: number;
+	bind?: ProviderChoiceBindingOptions;
+	storage?: ProviderChoiceStorageOptions;
+}
+
+export interface ProviderChoiceParseOptions {
+	token: string;
+	prefix: string;
+	purpose: string;
+	ttlMs?: number;
+	nowMs?: number;
+	futureToleranceMs?: number;
+	bind?: ProviderChoiceBindingOptions;
+	storage?: ProviderChoiceStorageOptions;
+}
+
+export interface ProviderChoiceContext {
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage?: { readonly mode: "inline" };
+		},
+	): string;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "server" }
+			>;
+		},
+	): Promise<string>;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "auto" }
+			>;
+		},
+	): string | Promise<string>;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload>,
+	): string | Promise<string>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage?: { readonly mode: "inline" };
+		},
+	): Record<string, unknown>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "server" }
+			>;
+		},
+	): Promise<Record<string, unknown>>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "auto" }
+			>;
+		},
+	): Record<string, unknown> | Promise<Record<string, unknown>>;
+	parse(options: ProviderChoiceParseOptions): Record<string, unknown>;
+}
+
 export interface ContextScratchpad {
 	get(key: string): unknown;
 	set(key: string, value: unknown): void;
@@ -450,8 +1403,11 @@ export interface FlowContext {
 	tenantId: string;
 	providerId: string;
 	http: HttpClient;
+	stealth: StealthClient;
 	env: EnvContext;
+	credential?: CredentialContext;
 	context: ContextScratchpad;
+	stt: SttContext;
 }
 
 export interface AuthTurn {
@@ -460,23 +1416,104 @@ export interface AuthTurn {
 	expiresAt?: string;
 	data?: Record<string, unknown>;
 	expectedInput?: Record<string, unknown>;
+	/**
+	 * @deprecated Compatibility-only materialized provider auth hint.
+	 * Provider source must emit hintKey; SDK/server boundaries may materialize
+	 * this field from provider locale catalogs for legacy clients.
+	 */
 	hint?: string;
+	/** Provider locale catalog key for the auth turn hint. */
+	hintKey?: ProviderLocaleKeyInput;
 	timing?: {
 		suggestedPollIntervalMs?: number;
 		maxWaitMs?: number;
 	};
 }
 
-export type AuthFlowHandler = (
+export type AuthFlowStartHandler = (ctx: FlowContext) => Promise<AuthTurn>;
+
+export type AuthFlowInputHandler = (
 	ctx: FlowContext,
 	input?: Record<string, unknown>,
 ) => Promise<AuthTurn>;
 
 export interface AuthFlowDefinition {
-	start: AuthFlowHandler;
-	continue: AuthFlowHandler;
-	poll?: AuthFlowHandler;
-	abort?: AuthFlowHandler;
+	start: AuthFlowStartHandler;
+	continue: AuthFlowInputHandler;
+	poll?: AuthFlowStartHandler;
+	abort?: AuthFlowStartHandler;
+	refresh?: AuthFlowInputHandler;
+}
+
+export type ProviderStateDurationString =
+	| `${number}${"ms" | "s" | "m" | "h" | "d"}`
+	| `PT${string}`;
+
+export interface StateNamespaceOptions {
+	/** Default TTL used when a write omits ttl. Required to avoid unbounded state. */
+	defaultTtl: ProviderStateDurationString;
+	/** Maximum allowed TTL; writes are rejected when they exceed this policy. */
+	maxTtl: ProviderStateDurationString;
+	/** Maximum number of live entries in this namespace scope. */
+	maxEntries: number;
+	/** Maximum JSON-encoded value size in bytes. */
+	maxValueBytes: number;
+}
+
+export interface StateWriteOptions {
+	ttl?: ProviderStateDurationString;
+}
+
+export interface StateValue<T = unknown> {
+	key: string;
+	value: T;
+	version: number;
+	expiresAt: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export type StateCasResult<T = unknown> =
+	| { ok: true; value: StateValue<T> }
+	| { ok: false; current: StateValue<T> | null };
+
+export interface ProviderStateNamespace {
+	list<T = unknown>(options?: {
+		limit?: number;
+		/** Optional literal key prefix used for scoped recovery scans. */
+		prefix?: string;
+	}): Promise<StateValue<T>[]>;
+	get<T = unknown>(key: string): Promise<StateValue<T> | null>;
+	set<T = unknown>(
+		key: string,
+		value: T,
+		options?: StateWriteOptions,
+	): Promise<StateValue<T>>;
+	patch<T extends Record<string, unknown>>(
+		key: string,
+		partial: Partial<T>,
+		options?: StateWriteOptions,
+	): Promise<StateValue<T>>;
+	compareAndSet<T = unknown>(
+		key: string,
+		expectedVersion: number,
+		value: T,
+		options?: StateWriteOptions,
+	): Promise<StateCasResult<T>>;
+	delete(key: string): Promise<void>;
+	increment(
+		key: string,
+		field: string,
+		delta?: number,
+		options?: StateWriteOptions,
+	): Promise<StateValue<Record<string, unknown>>>;
+}
+
+export interface ProviderRuntimeState {
+	namespace(
+		name: string,
+		options: StateNamespaceOptions,
+	): ProviderStateNamespace;
 }
 
 export interface ProviderContext {
@@ -484,10 +1521,14 @@ export interface ProviderContext {
 	credential: CredentialContext;
 	request?: ProviderRequestContext;
 	http: HttpClient;
-	tls: TlsClient;
+	cache: ProviderCache;
+	state: ProviderRuntimeState;
+	stealth: StealthClient;
 	browser: BrowserClient;
 	trace: TraceContext;
 	auth: AuthContext;
+	stt: SttContext;
+	choice: ProviderChoiceContext;
 }
 
 export interface AuthConfig {
@@ -511,29 +1552,59 @@ export interface ContextDeclaration {
 	keys: string[];
 }
 
+export type OperationLifecycle = "stable" | "beta" | "deprecated" | "removed";
+
+export interface OperationDeprecationMetadata {
+	announcedAt: string;
+	removalAfter: string;
+	replacement?: string;
+	migrationGuide: string;
+}
+
+export interface OperationContractMetadata {
+	/**
+	 * Callable operation contract version. Defaults to 1.0.0 for the clean
+	 * pre-GA baseline; it intentionally does not fall back to provider.version.
+	 */
+	version?: string;
+	lifecycle?: OperationLifecycle;
+	deprecation?: OperationDeprecationMetadata;
+}
+
 export interface OperationDefinition<
 	TInput extends SchemaLike = SchemaLike,
 	TOutput extends SchemaLike = SchemaLike,
 > {
-	description?: string;
+	descriptionKey?: ProviderLocaleKeyInput;
 	docs?: OperationDocMeta;
-	whenToUse?: string[];
-	whenNotToUse?: string[];
+	whenToUseKeys?: readonly ProviderLocaleKeyInput[];
+	whenNotToUseKeys?: readonly ProviderLocaleKeyInput[];
 	derivations?: Record<string, string>;
-	inputExamples?: OperationInputExample[];
+	inputExamples?: readonly OperationInputExample[];
 	annotations?: OperationAnnotations;
-	tags?: string[];
+	contract?: OperationContractMetadata;
+	tags?: readonly string[];
 	relatedOperations?: OperationRelationships;
+	toolRouter?: OperationToolRouterMetadata;
+	observability?: OperationObservabilityConfig;
+	transport?: OperationTransport;
+	retryOnAuthRefresh?: boolean;
 	input: TInput;
 	output: TOutput;
 	handler(
 		ctx: ProviderContext,
 		input: InferSchemaOutput<TInput>,
-	): Promise<InferSchemaOutput<TOutput>>;
+	):
+		| OperationHandlerResult<InferSchemaOutput<TOutput>>
+		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 	fixtures?: {
 		request: InferSchemaOutput<TInput>;
 		response: InferSchemaOutput<TOutput>;
 	};
+	upstream?: {
+		baseUrl?: string;
+		proxy?: boolean | ProviderProxyPolicy;
+	};
 	hints?: Record<string, string>;
 	healthCheck?: HealthCheckSuite<
 		InferSchemaOutput<TInput>,
@@ -551,16 +1622,19 @@ export interface ProviderDefinition {
 		profile: string;
 		platform: StealthPlatform;
 	};
-	proxy?: boolean;
+	proxy?: ProviderProxyConfig;
+	stt?: ProviderSttConfig;
 	browser?: {
 		engine: BrowserEngine;
 	};
 	auth?: AuthConfig;
 	reviewed?: ProviderReviewed;
+	access?: ProviderAccessConfig;
 	secrets?: ProviderSecretDeclaration[];
 	credential?: CredentialDeclaration;
 	context?: ContextDeclaration;
 	meta: ProviderMeta;
 	operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
 	healthMonitor?: ProviderHealthMonitorConfig;
+	healthJourneys?: readonly HealthJourneyDefinition[];
 }