@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

package/AUTHORING.md

@@ -18,6 +18,59 @@
 
 Provider code is the declaration input to the internal platform registry. The public SDK owns provider authoring/runtime ergonomics; internal docs, deploy, and discovery projections are built downstream from those declarations. `bun run lint:providers` enforces provider authoring standards.
 
+### User-input round-trips: never dead-end (`needs_input`)
+
+A mutation MUST NOT fail for a problem the end user can resolve by choosing among live options (a required menu/course selection, a form question, a stale-but-recoverable state token). Throwing an error there strands the consuming agent: consumer error-shaping layers routinely strip error metadata, and a model that only sees "error" narrates failure to the user instead of relaying the choice.
+
+Return the official success-shaped contract from `src/user-input.ts` instead (`ProviderNeedsInputPayload`, guard `isProviderNeedsInputPayload`):
+
+- `status: "needs_input"` plus `required_selections` — only the still-pending questions, with human-readable `label`s and `valid_options` the agent relays verbatim. The agent never chooses for the user; anything with no real choice (agreement checkboxes, single-option required groups) is the provider's job to auto-answer.
+- `selected_options` — selections already settled, echoed so the retry keeps them (copy them back and add the user's new answers).
+- a freshly minted provider state token in the same response, so the retry never races an expired token.
+
+No retry templates, next-action routing, or other agent choreography: provider payloads carry upstream-backed data only, and the consumer owns how the ask is phrased and how the retry call is shaped.
+
+Declare the union in the operation `output` schema (`z.union([CreatedSchema, NeedsInputSchema])`). Reserve hard errors for genuinely unrecoverable flows (payment-gated, unsupported input kinds) and state the concrete reason in the error `message` itself, not only in `details`. Reference implementation: `providers/catchtable` `reserve` in the platform monorepo.
+
+### Attempt tokens: the server carries the decisions
+
+When a mutation needs more than one user decision (or one decision plus a
+final go/no-go), do not make the agent re-send accumulated state across
+rounds — weak models drop or corrupt it. Split the operation into a
+**prepare/confirm pair** driven by a server-held attempt record:
+
+- The prepare operation is non-destructive. A start call takes only the
+  scalar intent fields; every response returns a fresh `attempt_token`
+  referencing a server-side record (`ctx.choice.issue` with
+  `storage.mode: "server"`) that stores every settled decision. Continue
+  calls take `attempt_token` plus only the NEW answers.
+- `needs_input` rounds list only the still-pending selections; settled
+  decisions may ride along in a display-only field but are never re-sent.
+- When nothing is pending, the prepare operation returns `status: "ready"`
+  with a human-readable summary — the consumer's user-facing confirmation.
+- The confirm operation is the only mutation and takes exactly
+  `{attempt_token}`. It re-validates everything live before executing and
+  returns `needs_input` (fresh token) instead of proceeding when upstream
+  drift invalidates a stored decision — never substitute a different option
+  for what the user picked.
+- Expired or foreign tokens fail factually (nothing happened; start a new
+  attempt with the scalar fields) — no answer salvage from a dead token.
+- **The provider must enforce consumption itself.** `ctx.choice` server
+  storage keeps tokens parseable until TTL — `parse` does not invalidate
+  them, so a confirm handler that only parses can be replayed into a second
+  booking or payment. After a successful execution, record the result under
+  the token's digest in `ctx.state` and make replays idempotent: a repeated
+  confirm returns the original created payload without touching upstream,
+  and later prepare rounds on the consumed token fail factually with the
+  existing reference. Record the result only after upstream success, so an
+  interrupted confirm stays retryable.
+
+The invariant behind all of it: complex flow state is the system's job, not
+the model's. The model carries exactly one opaque key between calls.
+Reference implementations: `providers/catchtable` `reserve`/`reserve-confirm`
+(including the consume-on-success guard) and `providers/modu-parking`
+payment state tokens in the platform monorepo.
+
 ### Description template
 
 Every operation `description` MUST be at least 150 characters and follow this structure:
@@ -256,6 +309,59 @@ External contributors are expected to submit standalone Provider source plus:
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Declared secrets are SDK-enforced
+
+Environment/secret presence validation is single-sourced in the SDK. Declare
+every env secret the provider needs in `defineProvider`:
+
+```ts
+secrets: [
+  {
+    name: "APIFUSE__PROVIDER__MY_PROVIDER__API_KEY",
+    required: true,
+    description: "Upstream API key from the vendor portal",
+  },
+],
+```
+
+The runtime validates every `required: true` declaration before any operation
+handler or auth-flow handler (except `abort`) runs. When a required secret is
+unset or whitespace-only, the invocation fails with the canonical structured
+error — code `MISSING_SECRET`, HTTP 400, `details.category:
+"credential_unavailable"`, `retryable: false`, and a `fix` naming every missing
+secret — across `/v1/{operation}`, self-test probes, `apifuse perf`, and
+`apifuse record`. The server also emits a `provider_secrets_missing` warn log
+at boot so unprovisioned deployments are visible immediately without crashing
+the pod.
+
+Provider-local presence re-validation is **deprecated**: do not write
+`requireServiceKey`/`requireApiKey`-style guards that re-check `ctx.env.get()`
+and throw a hand-rolled `CONFIGURATION_ERROR`/`MISSING_SECRET`. Those guards
+are dead weight (the SDK gate runs first) and historically diverged into
+inconsistent error shapes. The `sdk-owned-secret-presence` submit-check rule
+flags them at warn level; acknowledge a deliberate exception with
+`// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+
+```ts
+// Before (deprecated): provider-local double validation
+function requireServiceKey(ctx: ProviderContext): string {
+  const value = ctx.env.get(SERVICE_KEY_ENV);
+  if (!value?.trim()) {
+    throw new ProviderError(`Missing required provider secret: ${SERVICE_KEY_ENV}`, {
+      code: "CONFIGURATION_ERROR",
+    });
+  }
+  return value;
+}
+
+// After: declare { name: SERVICE_KEY_ENV, required: true } and read directly.
+const serviceKey = ctx.env.get(SERVICE_KEY_ENV);
+```
+
+Note the asymmetry: the gate treats whitespace-only values as missing, but
+`ctx.env.get()` still returns the raw value to handlers — trim at the point of
+use if the upstream is whitespace-sensitive.
+
 ### Public local debugging checklist
 
 - Operation smoke requests use the provider server envelope:

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.11
+
+- Release candidate for main commit f6f739bd5265afe714bbace9900edc2695fcf826.
+
+## 2.2.0-beta.10
+
+- Release candidate for main commit c41bd919739e0293ae8fa4d72a8a32f034cef4b8.
+
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
+## 2.2.0-beta.7
+
+- Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.
+
+## 2.2.0-beta.6
+
+- Release candidate for main commit 17f4e41d44efe7c148ef875b950be4f2c7df1294.
+
+## 2.2.0-beta.5
+
+- Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
+
+## 2.2.0-beta.4
+
+- Release candidate for main commit 73f2c6ec429c2fbce8ac458a67111e4844b99178.
+
+## 2.2.0-beta.3
+
+- Release candidate for main commit 74e8e18b502dd9b02dbf0d3e702f917570312fc0.
+
+## 2.2.0-beta.2
+
+- Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.
+
 ## 2.2.0-beta.1
 
 - Release candidate for main commit 5056b8c89fe0fa8f10bafcd30f83bcc421d4b5c5.
@@ -35,6 +75,7 @@
 ## Unreleased
 
 - Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
+- Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
 
 ## 2.1.0-beta.15
 

package/README.md

@@ -119,7 +119,11 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   local-only values through `connection.secrets`. Read them in handlers with
   `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
-  `.env`, and read only those names through `ctx.env.get("NAME")`.
+  `.env`, and read only those names through `ctx.env.get("NAME")`. The SDK
+  enforces presence of `required: true` declarations before handlers and auth
+  flows run, failing the invocation with a structured `MISSING_SECRET` error
+  (HTTP 400, category `credential_unavailable`) — do not re-check presence in
+  handlers.
 - **Credentials auth flows**: prefer `defineCredentialsAuth()` over hand-written
   `auth.flow`. Declare the form fields and credential keys once, then put the
   upstream login/session creation in `login(ctx, input)`. Return

package/SUBMISSION.md

@@ -50,7 +50,7 @@ Fix all blockers before submitting:
 - High-confidence secret or token material in source, README, package metadata, or fixtures.
 - SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.
 
-Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
+Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts, credentialed Providers that never reference `ctx.credential`, and provider-local re-validation of declared env secrets (`sdk-owned-secret-presence`, 0 points): the SDK already rejects invocations with a structured `MISSING_SECRET` error when a declared `required: true` secret is unset, so `requireServiceKey`-style presence guards are deprecated dead weight — delete the guard and read the value directly with `ctx.env.get()`, or acknowledge a deliberate exception with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
 
 ## Measured local smoke
 

package/bin/apifuse-check.ts

@@ -6,9 +6,14 @@ import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
-import type { ProviderDefinition } from "../src";
-import { lintProvider, type ProviderLintMode } from "../src/lint";
-import { safeParseSchemaSync } from "../src/schema";
+import {
+	formatPromptAssetIssues,
+	PROMPT_ASSET_SYNC_REMEDIATION,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import type { ProviderDefinition } from "../src/index.js";
+import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
 Example: apifuse check providers/korea-air-quality
@@ -24,9 +29,7 @@ export type RunChecksOptions = {
 	lintMode?: ProviderLintMode;
 };
 
-type SafeParseResult =
-	| { success: true; data: unknown }
-	| { success: false; error: unknown };
+type SafeParseResult = { success: true; data: unknown } | { success: false; error: unknown };
 
 export async function main() {
 	const args = normalizeArgs(process.argv.slice(2));
@@ -63,7 +66,7 @@ function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "check" ? argv.slice(1) : argv;
 }
 
-function resolveProviderRoot(inputPath: string): string {
+export function resolveProviderRoot(inputPath: string): string {
 	const resolvedInput = resolveFromParents(inputPath);
 
 	if (!existsSync(resolvedInput)) {
@@ -131,9 +134,26 @@ export async function runChecks(
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
+		checkPromptAssets(providerRoot),
 	];
 }
 
+export const PROMPT_ASSETS_CHECK_MESSAGE =
+	"Agent prompt assets match the installed SDK version";
+
+function checkPromptAssets(providerRoot: string): CheckResult {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return { message: PROMPT_ASSETS_CHECK_MESSAGE, passed: true };
+	}
+
+	return {
+		message: PROMPT_ASSETS_CHECK_MESSAGE,
+		passed: false,
+		details: [...formatPromptAssetIssues(verification), PROMPT_ASSET_SYNC_REMEDIATION],
+	};
+}
+
 function isScannableProviderSourceFile(relativePath: string): boolean {
 	return (
 		/\.(?:ts|tsx|js|jsx|mjs|cjs|sh|bash)$/.test(relativePath) ||
@@ -142,17 +162,12 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
-function collectProviderSourceFiles(
-	providerRoot: string,
-): Record<string, string> {
+function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
-	const skipDirectories = new Set([
-		".git",
-		"node_modules",
-		"dist",
-		"build",
-		".next",
-	]);
+	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
+	// is markdown/JSON (never matched by isScannableProviderSourceFile), and a
+	// planted `.ts`/`.sh` under those directories must stay in scanner scope.
+	const skipDirectories = new Set([".git", "node_modules", "dist", "build", ".next"]);
 	const visit = (directory: string) => {
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
@@ -162,10 +177,7 @@ function collectProviderSourceFiles(
 				}
 				continue;
 			}
-			if (
-				!entry.isFile() ||
-				!isScannableProviderSourceFile(path.slice(providerRoot.length + 1))
-			) {
+			if (!entry.isFile() || !isScannableProviderSourceFile(path.slice(providerRoot.length + 1))) {
 				continue;
 			}
 			sources[path.slice(providerRoot.length + 1)] = readFileSync(path, "utf8");
@@ -175,10 +187,7 @@ function collectProviderSourceFiles(
 	return sources;
 }
 
-function checkIndex(
-	indexPath: string,
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkIndex(indexPath: string, provider: ProviderDefinition | undefined): CheckResult {
 	if (!existsSync(indexPath)) {
 		return {
 			message: "index.ts exists and exports default defineProvider",
@@ -200,9 +209,7 @@ function checkIndex(
 	};
 }
 
-function checkOperations(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkOperations(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "All operations have handler, input, output",
@@ -277,20 +284,14 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 			continue;
 		}
 
-		const requestResult = parseFixture(
-			operation.input,
-			operation.fixtures.request,
-		);
+		const requestResult = parseFixture(operation.input, operation.fixtures.request);
 		if (!requestResult.success) {
 			failures.push(
 				`${operationId}: request fixture invalid (${formatSchemaError(requestResult.error)})`,
 			);
 		}
 
-		const responseResult = parseFixture(
-			operation.output,
-			operation.fixtures.response,
-		);
+		const responseResult = parseFixture(operation.output, operation.fixtures.response);
 		if (!responseResult.success) {
 			failures.push(
 				`${operationId}: response fixture invalid (${formatSchemaError(responseResult.error)})`,
@@ -317,13 +318,8 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider(
-		{ ...provider, providerSourceFiles },
-		{ mode: lintMode },
-	);
-	const errors = diagnostics.filter(
-		(diagnostic) => diagnostic.level === "error",
-	);
+	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
 	const details = diagnostics.map((diagnostic) => {
 		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
 		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
@@ -336,9 +332,7 @@ function checkAuthoringLint(
 	};
 }
 
-function checkProviderMetadata(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkProviderMetadata(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "Provider metadata is declared in defineProvider",
@@ -425,18 +419,12 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 	}
 }
 
-function assertProviderDefinition(
-	value: unknown,
-): ProviderDefinition | undefined {
+function assertProviderDefinition(value: unknown): ProviderDefinition | undefined {
 	return isProviderDefinition(value) ? value : undefined;
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 
@@ -457,8 +445,7 @@ function hasSchemaParser(value: unknown): boolean {
 	return (
 		isRecord(value) &&
 		(typeof value.safeParse === "function" ||
-			(isRecord(value["~standard"]) &&
-				typeof value["~standard"].validate === "function"))
+			(isRecord(value["~standard"]) && typeof value["~standard"].validate === "function"))
 	);
 }
 
@@ -470,9 +457,7 @@ function formatSchemaError(error: unknown): string {
 	if (Array.isArray(error)) {
 		return error
 			.map((issue) =>
-				isRecord(issue) && typeof issue.message === "string"
-					? issue.message
-					: String(issue),
+				isRecord(issue) && typeof issue.message === "string" ? issue.message : String(issue),
 			)
 			.join(", ");
 	}

package/bin/apifuse-create.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { main as runMain } from "../src/cli/create";
+import { main as runMain } from "../src/cli/create.js";
 
 export { runMain as main };
 

package/bin/apifuse-dev.ts

@@ -2,7 +2,7 @@
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src";
+import type { ProviderDefinition } from "../src/index.js";
 import {
 	createBrowserClient,
 	createCredentialContext,
@@ -14,10 +14,10 @@ import {
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	ProviderError,
-} from "../src";
-import { createMemoryProviderRuntimeState } from "../src/runtime/state";
-import { createTraceContext } from "../src/runtime/trace";
-import type { BrowserClient, ProviderContext } from "../src/types";
+} from "../src/index.js";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createTraceContext } from "../src/runtime/trace.js";
+import type { BrowserClient, ProviderContext } from "../src/types.js";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
 Example: apifuse dev providers/korea-air-quality
@@ -33,12 +33,9 @@ export async function main() {
 
 	const providerPath = resolveProviderPath(args[0] ?? ".");
 	const providerModule = await import(resolve(providerPath, "index.ts"));
-	const provider = assertProviderDefinition(
-		providerModule.default,
-		providerPath,
-	);
+	const provider = assertProviderDefinition(providerModule.default, providerPath);
 
-	const { startDevServer } = await import("../src/dev");
+	const { startDevServer } = await import("../src/dev.js");
 	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
 	startDevServer(provider, { port });
@@ -57,8 +54,7 @@ export async function main() {
 
 	const firstOperation = Object.keys(provider.operations)[0];
 	if (firstOperation) {
-		const sampleInput =
-			provider.operations[firstOperation]?.fixtures?.request ?? {};
+		const sampleInput = provider.operations[firstOperation]?.fixtures?.request ?? {};
 		const sampleBody = JSON.stringify({
 			requestId: `req_local_${firstOperation}`,
 			input: sampleInput,
@@ -149,9 +145,7 @@ function renderHotReloadCommand(providerPath: string, port: number): string {
 	const devEntry = resolve(providerPath, "dev.ts");
 	if (existsSync(devEntry)) {
 		const relativeDevEntry = relative(process.cwd(), devEntry) || "dev.ts";
-		const portPrefix = process.env.APIFUSE__RUNTIME__PORT
-			? `APIFUSE__RUNTIME__PORT=${port} `
-			: "";
+		const portPrefix = process.env.APIFUSE__RUNTIME__PORT ? `APIFUSE__RUNTIME__PORT=${port} ` : "";
 		return `${portPrefix}bun --hot ${relativeDevEntry}`;
 	}
 	return "rerun `apifuse dev` after edits (no dev.ts entrypoint found)";
@@ -166,40 +160,28 @@ function createUnsupportedBrowserStub(): BrowserClient {
 		engine: "playwright-stealth",
 		async close() {},
 		async newPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser',
+			});
 		},
 		async rawPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
+			});
 		},
 		async withIsolatedContext() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
+			});
 		},
 		async solveChallenge() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
+			});
 		},
 	};
 }
@@ -216,10 +198,7 @@ function createUnsupportedAuthStub() {
 	};
 }
 
-function assertProviderDefinition(
-	value: unknown,
-	providerPath: string,
-): ProviderDefinition {
+function assertProviderDefinition(value: unknown, providerPath: string): ProviderDefinition {
 	if (!isProviderDefinition(value)) {
 		throw new Error(
 			`Expected ${resolve(providerPath, "index.ts")} to export default defineProvider(...)`,
@@ -230,11 +209,7 @@ function assertProviderDefinition(
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 

package/bin/apifuse-pack-check.ts

@@ -48,6 +48,13 @@ const requiredPaths = [
 	"src/cli/templates/provider/operations/ping.ts.tpl",
 	"src/cli/templates/provider/schemas/ping.ts.tpl",
 	"src/cli/templates/provider/upstream/README.md.tpl",
+	"src/cli/templates/provider/AGENTS.md.tpl",
+	"src/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
 	"dist/cli/templates/provider/.dockerignore.tpl",
 	"dist/cli/templates/provider/.gitignore.tpl",
 	"dist/cli/templates/provider/Dockerfile.tpl",
@@ -60,6 +67,13 @@ const requiredPaths = [
 	"dist/cli/templates/provider/operations/ping.ts.tpl",
 	"dist/cli/templates/provider/schemas/ping.ts.tpl",
 	"dist/cli/templates/provider/upstream/README.md.tpl",
+	"dist/cli/templates/provider/AGENTS.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
 	"dist/auth-turn/index.js",
 	"dist/auth-turn/index.d.ts",
 	"dist/auth-turn/auth-turn.v1.schema.json",