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

package/AUTHORING.md

@@ -2,7 +2,7 @@
 
 - Canonical scaffolding command: `apifuse create`
 - Monorepo contributors should use `apifuse create <name> --preset monorepo`
-- Standalone users should use `bunx @apifuse/provider-sdk create <name>`
+- Standalone bounty contributors should use `bunx @apifuse/provider-sdk@beta create <name> --yes` until this release is promoted to `latest`
 - Provider server contract is:
   - dev default `3900`
   - start/Docker/container `3000`
@@ -47,6 +47,7 @@ description:
 - `description` — 150+ chars English (error-level rule)
 - Every Zod field in input AND output has `.describe()` including nested objects + array items (error-level rule)
 - `fixtures.request` + `fixtures.response` both present (error-level rule)
+- Exactly one of `healthCheck` or `healthCheckUnsupported` per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes.
 
 ### Factored operations
 
@@ -62,31 +63,21 @@ Use `defineOperation()` when an operation is large enough to live beside helper
 
 - `annotations`: `{ readOnly, destructive, idempotent, openWorld, rateLimit }` — agentic safety signals
 - `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
-- `relatedOperations`: `{ alternatives?: string[]; chainsWith?: string[] }` — links to related operations for composite/fallback suggestions
+- `relatedOperations`: `{ alternatives?: string[] }` — links to fallback/sibling operations
 
-### Composite operations
+### External bounty submission evidence
 
-For multi-step chains (e.g., geocode → transform → forecast), use `defineCompositeOperation()` from `@apifuse/provider-sdk`:
+External contributors are expected to submit standalone Provider source plus:
 
-```ts
-import { defineCompositeOperation, z } from "@apifuse/provider-sdk"
-
-export const weatherByAddress = defineCompositeOperation({
-  id: "kma:weather-by-address",
-  description: "...",
-  input: z.object({ address: z.string().describe("...") }),
-  output: ResultSchema,
-  tags: ["weather", "korea", "composite"],
-  chainsWith: ["kakaomap:geocode", "kma:short-forecast"],
-  steps: async (ctx, input) => {
-    const geo = await ctx.chain.call("kakaomap:geocode", { address: input.address })
-    if (geo.items.length === 0) {
-      return ctx.clarify({ question: "...", missing: [{ name: "address", description: "..." }] })
-    }
-    // ... continue chain
-  },
-})
-```
+- SDK version/tag and create command used.
+- Provider id, version, runtime, auth mode, and Operation list.
+- Health coverage table for every Operation.
+- `bun run check` output.
+- `bun run test` output.
+- Fixture evidence and known upstream constraints.
+
+Maintainers own monorepo import under `providers/<id>/`, registry generation,
+deployment projection checks, and release workflows.
 
 ### Running the lint locally
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.1
+
+- Fix public `apifuse create` runtime packaging by publishing `@clack/prompts` as a production dependency.
+- Update generated Provider starter templates so the sample operation declares a local-only `healthCheckUnsupported` and passes the current health coverage contract.
+- Add packed-artifact smoke coverage for the public create/check/test flow before npm release publishing.
+- Document the public SDK-only bounty contributor path and maintainer-owned monorepo import boundary.
+
 ## 2.1.0-beta.0
 
 - BREAKING: collapse the Chrome desktop stealth catalog to `chrome-146` plus the `chrome-desktop` alias. Removed/blocked `chrome-120`, `chrome-124`, `chrome-129`, `chrome-130`, `chrome-131`, `chrome-133`, `chrome-144`, `chrome-146-psk`, `chrome-131-psk`, `chrome-130-psk`, and `edge-131`; migrate callers to `chrome-146`.

package/README.md

@@ -8,12 +8,19 @@ ApiFuse Provider SDK — build provider declarations and runtimes with one publi
 bun add @apifuse/provider-sdk
 ```
 
+For external bounty scaffolding, use the beta tag until this release is promoted
+to `latest`:
+
+```bash
+bunx @apifuse/provider-sdk@beta create my-provider --yes
+```
+
 ## Create a provider
 
 ### Standalone (default)
 
 ```bash
-bunx @apifuse/provider-sdk create my-provider
+bunx @apifuse/provider-sdk@beta create my-provider --yes
 ```
 
 The canonical `create` flow:
@@ -49,9 +56,18 @@ Removed legacy runtime paths are not supported:
 
 ```bash
 cd my-provider
-bun run dev
 bun run check
 bun run test
+bun run dev
+```
+
+Smoke the generated local server:
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"value":"hello"},"headers":{},"connection":null}'
 ```
 
 ## Authoring ergonomics
@@ -80,6 +96,18 @@ export default defineProvider({
 
 Operation schemas may be Zod schemas or Standard Schema v1-compatible schemas. Invalid configs throw `ProviderError`/`ValidationError` messages that name the offending field, such as `auth.mode` or `operations.search.fixtures.request`.
 
+### Operation health coverage
+
+Every operation must declare exactly one of:
+
+- `healthCheck` — preferred for safe read-only upstream probes.
+- `healthCheckUnsupported` — allowed only when a probe is destructive, paid,
+  credential-sensitive, flaky by design, or otherwise unsafe. The `reason` must
+  be specific.
+
+The generated `ping` operation uses `healthCheckUnsupported` only because it is
+a local scaffold check, not a real upstream API probe.
+
 ### Operation annotations
 
 Operations declare non-functional metadata via `annotations`:
@@ -114,3 +142,8 @@ Generator v1 scaffolds **TypeScript providers only** for this redesign. Python g
 ## Boundary
 
 Provider cataloging, deployment enrollment, docs indexing, and runtime discovery are internal platform-registry responsibilities and are not part of the public `@apifuse/provider-sdk` contract.
+
+External bounty contributors should submit standalone Provider source plus
+`bun run check` / `bun run test` evidence. ApiFuse maintainers own monorepo
+import, registry generation, deployment projection checks, and release
+publishing.

package/bin/apifuse-pack-check.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 
 const PACK_RESULT_SCHEMA = z.array(
@@ -28,12 +29,23 @@ if (!first) {
 }
 
 const filePaths = (first.files ?? []).map((file) => file.path);
+const requiredPaths = [
+	"bin/apifuse.ts",
+	"bin/apifuse-create.ts",
+	"bin/apifuse-pack-smoke.ts",
+	"src/cli/create.ts",
+	"src/cli/templates/provider/index.ts.tpl",
+	"src/cli/templates/provider/README.md.tpl",
+];
 const forbiddenMatches = filePaths.filter(
 	(path) =>
 		path.startsWith("src/__tests__/") ||
 		path === "src/index.test.ts" ||
 		path === "bin/apifuse-init.ts",
 );
+const missingRequiredPaths = requiredPaths.filter(
+	(path) => !filePaths.includes(path),
+);
 
 if (forbiddenMatches.length > 0) {
 	throw new Error(
@@ -41,6 +53,34 @@ if (forbiddenMatches.length > 0) {
 	);
 }
 
+if (missingRequiredPaths.length > 0) {
+	throw new Error(
+		`Packed artifact is missing required public SDK files:\n${missingRequiredPaths.join("\n")}`,
+	);
+}
+
+const packageJsonInput: unknown = JSON.parse(
+	readFileSync("package.json", "utf8"),
+);
+const packageJson = z
+	.object({
+		dependencies: z.record(z.string(), z.string()).optional(),
+		devDependencies: z.record(z.string(), z.string()).optional(),
+	})
+	.parse(packageJsonInput);
+
+if (!packageJson.dependencies?.["@clack/prompts"]) {
+	throw new Error(
+		"@clack/prompts is imported by the public create CLI and must be listed in dependencies.",
+	);
+}
+
+if (packageJson.devDependencies?.["@clack/prompts"]) {
+	throw new Error(
+		"@clack/prompts must not be devDependency-only because the published create CLI imports it at runtime.",
+	);
+}
+
 console.log(`Packed artifact OK: ${first.filename}`);
 for (const filePath of filePaths) {
 	console.log(`  - ${filePath}`);

package/bin/apifuse-pack-smoke.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env bun
+
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+
+const PACK_RESULT_SCHEMA = z.array(
+	z.object({
+		filename: z.string(),
+	}),
+);
+
+const KEEP_TEMP = process.env.APIFUSE_PACK_SMOKE_KEEP_TEMP === "1";
+
+const tempRoot = mkdtempSync(
+	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
+);
+const packDir = join(tempRoot, "pack");
+const consumerDir = join(tempRoot, "consumer");
+
+try {
+	mkdirSync(packDir, { recursive: true });
+	mkdirSync(consumerDir, { recursive: true });
+
+	const packed = packSdk(packDir);
+	const tarballPath = resolve(packDir, packed.filename);
+	const tarballSpecifier = `file:${tarballPath}`;
+
+	writeFileSync(
+		join(consumerDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				dependencies: {
+					"@apifuse/provider-sdk": tarballSpecifier,
+				},
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	run("bun", ["install"], consumerDir);
+
+	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
+	if (!existsSync(cliBin)) {
+		throw new Error(`Expected CLI bin at ${cliBin}`);
+	}
+
+	run(
+		"bun",
+		[
+			cliBin,
+			"create",
+			"dx-smoke",
+			"--yes",
+			"--json",
+			"--sdk-specifier",
+			tarballSpecifier,
+		],
+		consumerDir,
+	);
+
+	const generatedProviderDir = join(consumerDir, "dx-smoke");
+	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "test"], generatedProviderDir);
+
+	console.log(
+		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
+	);
+} finally {
+	if (KEEP_TEMP) {
+		console.log(`Keeping smoke temp directory: ${tempRoot}`);
+	} else {
+		rmSync(tempRoot, { recursive: true, force: true });
+	}
+}
+
+function packSdk(destination: string): { filename: string } {
+	const raw = execFileSync(
+		"npm",
+		["pack", "--json", "--pack-destination", destination],
+		{
+			cwd: process.cwd(),
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "inherit"],
+		},
+	);
+	const parsed = PACK_RESULT_SCHEMA.parse(JSON.parse(raw));
+	const first = parsed[0];
+	if (!first) {
+		throw new Error("npm pack --json returned no package metadata.");
+	}
+	return first;
+}
+
+function run(command: string, args: string[], cwd: string): void {
+	const result = spawnSync(command, args, {
+		cwd,
+		env: process.env,
+		stdio: "inherit",
+	});
+
+	if (result.error) {
+		throw result.error;
+	}
+
+	if (result.status !== 0) {
+		throw new Error(
+			`Command failed (${[command, ...args].join(" ")}) in ${cwd} with exit code ${result.status}`,
+		);
+	}
+}

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.0",
+	"version": "2.1.0-beta.1",
 	"private": false,
 	"type": "module",
-	"description": "ApiFuse Provider SDK \u2014 Build providers with zero architectural constraints",
+	"description": "ApiFuse Provider SDK — Build providers with zero architectural constraints",
 	"license": "MIT",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
@@ -61,16 +61,17 @@
 		"type-check": "tsgo --noEmit",
 		"test": "bun test",
 		"check": "bun run lint && bun run type-check",
-		"pack:check": "bun bin/apifuse-pack-check.ts"
+		"pack:check": "bun bin/apifuse-pack-check.ts",
+		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.12",
-		"@clack/prompts": "^1.2.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.1.0",
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {
+		"@clack/prompts": "^1.2.0",
 		"ajv": "^8.17",
 		"hono": "^4.12.14",
 		"playwright": "^1.55.1",

package/src/ceremonies/index.ts

@@ -63,6 +63,7 @@ const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
 const SWITCH_SELECTION_KEY = "__switch_selection";
+const FORM_FIELD_ORDER_EXTENSION = "x-apifuse-field-order";
 
 function isRecord(value: unknown): value is JsonObject {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -175,11 +176,31 @@ function buildJsonSchemaForm(
 ): AuthTurn {
 	return createTurn("form", {
 		hint,
-		expectedInput,
+		expectedInput: withDeclaredFormFieldOrder(expectedInput),
 		data: {},
 	});
 }
 
+function withDeclaredFormFieldOrder(expectedInput: JsonObject): JsonObject {
+	const properties = expectedInput.properties;
+	if (!isRecord(properties)) {
+		return expectedInput;
+	}
+
+	const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
+	if (
+		Array.isArray(existingOrder) &&
+		existingOrder.every((value) => typeof value === "string")
+	) {
+		return expectedInput;
+	}
+
+	return {
+		...expectedInput,
+		[FORM_FIELD_ORDER_EXTENSION]: Object.keys(properties),
+	};
+}
+
 export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	if (!validateAuthTurn(turn)) {
 		const detail = validateAuthTurn.errors

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

@@ -25,4 +25,17 @@ bun run test
 
 1. Replace the sample `ping` operation with real upstream logic.
 2. Record a real fixture with `bun run record:sample` or a provider-specific equivalent.
-3. Extend tests and operation metadata until the provider is bounty-ready.
+3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
+4. Extend tests and operation metadata until the provider is bounty-ready.
+
+## Health-check authorship
+
+Every operation must declare exactly one of:
+
+- `healthCheck` — preferred for safe read-only upstream probes.
+- `healthCheckUnsupported` — allowed only when a probe is destructive, paid,
+  credential-sensitive, flaky by design, or otherwise unsafe. Use a specific
+  reason; reviewers reject placeholder reasons such as "TODO" or "later".
+
+The generated `ping` operation uses `healthCheckUnsupported` only because it is
+a local scaffold check, not a real upstream API probe.

package/src/cli/templates/provider/index.ts.tpl

@@ -49,6 +49,10 @@ export default defineProvider({
         request: { value: "hello" },
         response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
       },
+      healthCheckUnsupported: {
+        reason:
+          "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+      },
     },
   },
 });

package/src/config/loader.ts

@@ -43,7 +43,67 @@ export type ResolvedProxyConfig = {
 
 function normalizeProxyUrl(url?: string): string | undefined {
 	const normalized = url?.trim();
-	return normalized ? normalized : undefined;
+	return normalized ? applyStickyProxySession(normalized) : undefined;
+}
+
+function applyStickyProxySession(proxyUrl: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(proxyUrl);
+	} catch {
+		return proxyUrl;
+	}
+
+	if (!parsed.hostname || !parsed.username || !parsed.password) {
+		return proxyUrl;
+	}
+
+	const host = parsed.hostname.toLowerCase();
+	if (!host.includes("smartproxy") && !host.includes("decodo")) {
+		return proxyUrl;
+	}
+
+	const username = decodeURIComponent(parsed.username);
+	const sessionId =
+		process.env.APIFUSE_PROXY_SESSION_ID?.trim() || "apifuse-shared";
+	const sessionDuration =
+		process.env.APIFUSE_PROXY_SESSION_DURATION?.trim() || undefined;
+	const stickyUsername = host.includes("smartproxy")
+		? buildSmartproxyUsername(username, sessionId, sessionDuration)
+		: buildDecodoUsername(username, sessionId, sessionDuration ?? "60");
+
+	parsed.username = stickyUsername;
+	return parsed.toString();
+}
+
+function buildSmartproxyUsername(
+	username: string,
+	sessionId: string,
+	sessionDuration?: string,
+): string {
+	const parts = username.split("_");
+	const configuredLife = parts
+		.find((part) => part.startsWith("life-"))
+		?.slice("life-".length);
+	const baseUsername = parts
+		.filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
+		.join("_");
+	return `${baseUsername}_session-${sessionId}_life-${sessionDuration ?? configuredLife ?? "60"}`;
+}
+
+function buildDecodoUsername(
+	username: string,
+	sessionId: string,
+	sessionDuration: string,
+): string {
+	const withoutSticky = username.replace(
+		/-session-.+-sessionduration-\d+$/,
+		"",
+	);
+	const baseUsername = withoutSticky.startsWith("user-")
+		? withoutSticky
+		: `user-${withoutSticky}`;
+	return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
 }
 
 function syncProxyEnv(config: ApiFuseConfig): void {

package/src/define.ts

@@ -233,8 +233,10 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
 const HEALTH_CHECK_UNSUPPORTED_FIELDS = new Set(["reason", "trackedIn"]);
 const PROVIDER_HEALTH_MONITOR_FIELDS = new Set([
 	"requiredSecrets",
+	"probeOverrides",
 	"serviceAccount",
 ]);
+const PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS = new Set(["interval"]);
 
 function levenshtein(a: string, b: string): number {
 	const m = a.length;
@@ -307,13 +309,13 @@ function validateProviderHealthMonitor(
 				fix: `Set healthMonitor to { requiredSecrets?: string[]; serviceAccount?: string }`,
 			},
 		);
+	const healthMonitorRecord = Object.fromEntries(Object.entries(healthMonitor));
 	rejectUnknownFields(
-		healthMonitor as Record<string, unknown>,
+		healthMonitorRecord,
 		PROVIDER_HEALTH_MONITOR_FIELDS,
 		"healthMonitor",
 	);
-	const requiredSecrets = (healthMonitor as ProviderHealthMonitorConfig)
-		.requiredSecrets;
+	const requiredSecrets = healthMonitorRecord.requiredSecrets;
 	if (requiredSecrets !== undefined) {
 		if (!Array.isArray(requiredSecrets))
 			throw new ValidationError(
@@ -326,8 +328,44 @@ function validateProviderHealthMonitor(
 				);
 		}
 	}
-	const serviceAccount = (healthMonitor as ProviderHealthMonitorConfig)
-		.serviceAccount;
+	const probeOverrides = healthMonitorRecord.probeOverrides;
+	if (probeOverrides !== undefined) {
+		if (
+			!probeOverrides ||
+			typeof probeOverrides !== "object" ||
+			Array.isArray(probeOverrides)
+		)
+			throw new ValidationError(
+				`Provider "${providerId}" has invalid healthMonitor.probeOverrides: must be an object keyed by probe id.`,
+			);
+		for (const [probeId, override] of Object.entries(probeOverrides)) {
+			if (probeId.length === 0)
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides key: must be a non-empty probe id.`,
+				);
+			if (!override || typeof override !== "object" || Array.isArray(override))
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"]: must be an object.`,
+				);
+			const overrideRecord = Object.fromEntries(Object.entries(override));
+			rejectUnknownFields(
+				overrideRecord,
+				PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS,
+				`healthMonitor.probeOverrides["${probeId}"]`,
+			);
+			const interval = overrideRecord.interval;
+			const validProbeIntervals: readonly string[] = PROBE_INTERVALS;
+			if (
+				interval !== undefined &&
+				(typeof interval !== "string" ||
+					!validProbeIntervals.includes(interval))
+			)
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"].interval: must be one of ${PROBE_INTERVALS.join(", ")}.`,
+				);
+		}
+	}
+	const serviceAccount = healthMonitorRecord.serviceAccount;
 	if (
 		serviceAccount !== undefined &&
 		(typeof serviceAccount !== "string" || serviceAccount.length === 0)

package/src/index.ts

@@ -2,12 +2,6 @@
 
 export { z } from "zod";
 export * from "./ceremonies";
-export {
-	type ClarifyResponse,
-	type CompositeContext,
-	type CompositeOperationDefinition,
-	defineCompositeOperation,
-} from "./composite";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,

package/src/provider.ts

@@ -1,7 +1,6 @@
 export { z } from "zod";
 
 export { createFormCeremony } from "./ceremonies";
-export { defineCompositeOperation } from "./composite";
 export { defineOperation, defineProvider } from "./define";
 export { AuthError, ProviderError, ValidationError } from "./errors";
 export type {

package/src/runtime/http.ts

@@ -83,13 +83,12 @@ async function doRequest(
 		});
 
 		if (!response.ok) {
-			const text = await response.text().catch(() => "");
+			await drainFetchResponse(response);
 			throw new TransportError(
-				`HTTP ${response.status} ${response.statusText}: ${requestUrl}`,
+				`Upstream request failed with status ${response.status}`,
 				{
 					code: "upstream_http_error",
 					status: response.status,
-					fix: `Check the endpoint URL and request parameters. Response: ${text.slice(0, 200)}`,
 				},
 			);
 		}
@@ -121,16 +120,12 @@ async function doRequest(
 		}
 
 		if (error instanceof Error && error.name === "AbortError") {
-			throw new TransportError(
-				`Request timed out: ${resolveUrl(baseUrl, url)}`,
-				{
-					code: "transport_timeout",
-					fix: `Increase timeout option (current: ${timeout}ms)`,
-				},
-			);
+			throw new TransportError("Request timed out", {
+				code: "transport_timeout",
+			});
 		}
 
-		throw new TransportError(`Network error: ${String(error)}`, {
+		throw new TransportError("Network error", {
 			code: "transport_network_error",
 			cause: error instanceof Error ? error : undefined,
 		});
@@ -141,6 +136,27 @@ async function doRequest(
 	}
 }
 
+async function drainFetchResponse(response: Response): Promise<void> {
+	const reader = response.body?.getReader();
+	if (!reader) {
+		return;
+	}
+
+	try {
+		while (true) {
+			const { done } = await reader.read();
+			if (done) {
+				return;
+			}
+		}
+	} catch {
+		// Best-effort drain for transport reuse only; callers still receive the
+		// sanitized upstream error below.
+	} finally {
+		reader.releaseLock();
+	}
+}
+
 function createProxyInit(
 	proxy?: string,
 ): Pick<FetchProxyInit, "dispatcher" | "proxy"> {

package/src/runtime/tls.ts

@@ -19,6 +19,12 @@ const MISSING_PROXY_WARNING =
 
 export type TlsClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
+	/**
+	 * Proxy-only TLS transport overrides. Use only for upstream proxy products
+	 * that terminate CONNECT with a private CA instead of tunneling the origin
+	 * certificate chain.
+	 */
+	proxyTls?: { insecureSkipVerify?: boolean };
 };
 
 const REMOVED_CHROME_PROFILE_NAMES = new Set([
@@ -187,14 +193,6 @@ export function normalizeResponse(
 	};
 }
 
-function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) {
-		return error.toString();
-	}
-
-	return String(error);
-}
-
 function normalizeBody(body: TlsFetchOptions["body"]): string | null {
 	if (body === undefined) {
 		return null;
@@ -274,6 +272,7 @@ function createSessionFetcher(
 	let sessionClient: SessionClient | null = null;
 	let activeProxy: string | undefined;
 	let activeTlsIdentifier: string | undefined;
+	let activeInsecureSkipVerify = false;
 	let hasWarnedMissingProxy = false;
 	const warn = clientOptions.warn ?? console.warn;
 
@@ -305,19 +304,22 @@ function createSessionFetcher(
 		sessionClient = null;
 		activeProxy = undefined;
 		activeTlsIdentifier = undefined;
+		activeInsecureSkipVerify = false;
 	}
 
 	function getSessionClient(
 		profile?: string,
 		proxy?: string,
 		ja3?: string,
+		insecureSkipVerify = false,
 	): SessionClient {
 		const tlsIdentifier = ja3 ?? resolveIdentifier(profile ?? defaultProfile);
 
 		if (
 			!sessionClient ||
 			activeProxy !== proxy ||
-			activeTlsIdentifier !== tlsIdentifier
+			activeTlsIdentifier !== tlsIdentifier ||
+			activeInsecureSkipVerify !== insecureSkipVerify
 		) {
 			if (sessionClient) {
 				closeCurrentSession();
@@ -326,10 +328,12 @@ function createSessionFetcher(
 			sessionClient = new SessionClient(moduleClient, {
 				tlsClientIdentifier: tlsIdentifier,
 				...(proxy ? { proxyUrl: proxy } : {}),
+				...(insecureSkipVerify ? { insecureSkipVerify: true } : {}),
 				timeoutSeconds: 30,
 			} as ConstructorParameters<typeof SessionClient>[1]);
 			activeProxy = proxy;
 			activeTlsIdentifier = tlsIdentifier;
+			activeInsecureSkipVerify = insecureSkipVerify;
 		}
 
 		return sessionClient;
@@ -338,10 +342,15 @@ function createSessionFetcher(
 	return {
 		async fetch(url, options = {}) {
 			const proxy = resolveRequestProxy(options);
+			const insecureSkipVerify = Boolean(
+				options.tls?.insecureSkipVerify ??
+					(proxy && clientOptions.proxyTls?.insecureSkipVerify),
+			);
 			const session = getSessionClient(
 				options.profile,
 				proxy,
 				options.tls?.ja3,
+				insecureSkipVerify,
 			);
 			const requestUrl = resolveUrl(baseUrl, url);
 
@@ -352,9 +361,9 @@ function createSessionFetcher(
 					proxy,
 				});
 
-				if (response.status >= 400) {
+				if (response.status >= 400 && options.throwOnHttpError !== false) {
 					throw new TransportError(
-						`HTTP ${response.status}: ${response.body || "Request failed"}`,
+						`Upstream request failed with status ${response.status}`,
 						{
 							status: response.status,
 						},
@@ -367,7 +376,7 @@ function createSessionFetcher(
 					throw error;
 				}
 
-				throw new TransportError(`Network error: ${getErrorMessage(error)}`, {
+				throw new TransportError("Network error", {
 					status: 0,
 					cause: error instanceof Error ? error : undefined,
 				});

package/src/server/serve.ts

@@ -215,9 +215,8 @@ function toErrorResponse(
 		return {
 			error: {
 				code: error.code ?? "provider_error",
-				message: error.message,
+				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
-				...(error.fix ? { fix: error.fix } : {}),
 				...(error instanceof TransportError && error.status
 					? { details: { upstreamStatus: error.status } }
 					: {}),
@@ -245,6 +244,21 @@ function toErrorResponse(
 	};
 }
 
+function publicProviderErrorMessage(error: ProviderError): string {
+	if (error instanceof TransportError) {
+		if (error.code === "transport_timeout") return "Request timed out";
+		if (error.code === "transport_network_error") return "Network error";
+		if (error.code === "upstream_http_error" && error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		if (error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		return "Upstream request failed";
+	}
+	return error.message;
+}
+
 function toStatusCode(error: unknown): 400 | 404 | 500 | 502 | 504 {
 	if (error instanceof z.ZodError) {
 		return 400;
@@ -255,7 +269,7 @@ function toStatusCode(error: unknown): 400 | 404 | 500 | 502 | 504 {
 	}
 
 	if (error instanceof ProviderError) {
-		if (error.code === "NOT_FOUND") {
+		if (error.code === "NOT_FOUND" || error.code === "NO_DATA") {
 			return 404;
 		}
 

package/src/types.ts

@@ -82,7 +82,6 @@ export const OPERATION_TIMEOUT_MS_MAX = 60_000;
 
 export interface OperationRelationships {
 	alternatives?: string[];
-	chainsWith?: string[];
 }
 
 /**
@@ -97,7 +96,15 @@ export interface OperationRelationships {
  */
 
 /** Polling intervals supported by the health-monitor runtime. */
-export type ProbeInterval = "30s" | "1m" | "3m" | "5m" | "15m" | "30m" | "1h";
+export type ProbeInterval =
+	| "30s"
+	| "1m"
+	| "3m"
+	| "5m"
+	| "15m"
+	| "30m"
+	| "1h"
+	| "24h";
 
 export const PROBE_INTERVALS: readonly ProbeInterval[] = [
 	"30s",
@@ -107,6 +114,7 @@ export const PROBE_INTERVALS: readonly ProbeInterval[] = [
 	"15m",
 	"30m",
 	"1h",
+	"24h",
 ] as const;
 
 /**
@@ -222,6 +230,13 @@ export interface ProviderHealthMonitorConfig {
 	 * `requiresConnection: true`.
 	 */
 	requiredSecrets?: string[];
+	/**
+	 * Runtime probe overrides keyed by probe id (for example
+	 * "catchtable/auth-flow" or "catchtable/waiting-lifecycle"). Use this for
+	 * health-monitor probes that are provider-scoped or cross-operation and
+	 * therefore cannot declare an `OperationDefinition.healthCheck.interval`.
+	 */
+	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.
@@ -229,6 +244,11 @@ export interface ProviderHealthMonitorConfig {
 	serviceAccount?: string;
 }
 
+export interface HealthMonitorProbeOverride {
+	/** Optional runtime interval override. Must be one of PROBE_INTERVALS. */
+	interval?: ProbeInterval;
+}
+
 export interface OperationErrorCode {
 	code: string;
 	status?: number;
@@ -300,9 +320,15 @@ export interface TlsFetchOptions extends RequestOptions {
 	method?: string;
 	body?: string | Buffer;
 	profile?: string;
+	/**
+	 * Defaults to true. Set to false when callers need to inspect upstream
+	 * non-2xx bodies themselves instead of converting them to TransportError.
+	 */
+	throwOnHttpError?: boolean;
 	tls?: {
 		ja3?: string;
 		h2?: Record<string, unknown>;
+		insecureSkipVerify?: boolean;
 	};
 	headerOrder?: string[];
 }

package/src/composite.ts

@@ -1,43 +0,0 @@
-import type { infer as ZodInfer, ZodType } from "zod";
-
-export interface ClarifyResponse {
-	_type: "clarify";
-	question: string;
-	missing: Array<{ name: string; description: string }>;
-}
-
-export interface CompositeContext {
-	chain: {
-		call: <T>(operationKey: string, params: unknown) => Promise<T>;
-	};
-	clarify: (opts: {
-		question: string;
-		missing: Array<{ name: string; description: string }>;
-	}) => ClarifyResponse;
-	setSlot: (name: string, value: unknown) => void;
-}
-
-export interface CompositeOperationDefinition<
-	TInput extends ZodType = ZodType,
-	TOutput extends ZodType = ZodType,
-> {
-	id: string;
-	description: string;
-	input: TInput;
-	output: TOutput;
-	tags?: string[];
-	chainsWith?: string[];
-	steps: (
-		ctx: CompositeContext,
-		input: ZodInfer<TInput>,
-	) => Promise<ZodInfer<TOutput> | ClarifyResponse>;
-}
-
-export function defineCompositeOperation<
-	TInput extends ZodType,
-	TOutput extends ZodType,
->(
-	config: CompositeOperationDefinition<TInput, TOutput>,
-): CompositeOperationDefinition<TInput, TOutput> {
-	return config;
-}