@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.8

package/AUTHORING.md

@@ -309,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,17 @@
 # @apifuse/provider-sdk Changelog
 
+## 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.

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,6 +6,11 @@ import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
+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";
@@ -61,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)) {
@@ -129,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,6 +164,9 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
+	// `.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 })) {

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",

package/bin/apifuse-submit-check.ts

@@ -11,6 +11,10 @@ import * as acorn from "acorn";
 import { z } from "zod";
 
 import packageJson from "../package.json";
+import {
+	formatPromptAssetIssues,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
 import type { ProviderDefinition } from "../src/index.js";
 import {
 	loadProviderLocaleCatalogs,
@@ -19,7 +23,7 @@ import {
 } from "../src/i18n/index.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema.js";
 import { safeParseSchemaSync } from "../src/schema.js";
-import { type CheckResult, runChecks } from "./apifuse-check.js";
+import { type CheckResult, PROMPT_ASSETS_CHECK_MESSAGE, runChecks } from "./apifuse-check.js";
 import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
@@ -267,7 +271,15 @@ export async function buildSubmitCheckReport(
 	const baseChecks = await safeRunChecks(providerRoot);
 	const provider = await safeLoadProvider(providerRoot);
 
-	checks.push(...scoreBaseChecks(baseChecks));
+	// Prompt-asset freshness is reported by its own dedicated zero-point
+	// blocker below; filter the base-check duplicate so it is not double
+	// penalized under the definition category.
+	checks.push(
+		...scoreBaseChecks(
+			baseChecks.filter((result) => result.message !== PROMPT_ASSETS_CHECK_MESSAGE),
+		),
+	);
+	checks.push(scorePromptAssetFreshness(providerRoot));
 	checks.push(scoreProviderIdSlug(providerRoot, provider));
 	checks.push(scoreNoVendorShim(providerRoot));
 	checks.push(scoreNoVendorImport(providerRoot));
@@ -283,6 +295,7 @@ export async function buildSubmitCheckReport(
 	if (provider) {
 		const smokeResult = args.smoke ? await runSubmitCheckSmoke(providerRoot, provider) : undefined;
 		checks.push(scoreCredentialUsage(providerRoot, provider));
+		checks.push(scoreSdkOwnedSecretPresence(providerRoot, provider));
 		checks.push(scoreLocaleCatalog(providerRoot, provider));
 		checks.push(scoreOperationMetadata(provider));
 		checks.push(scoreFixtureCoverage(provider));
@@ -1424,6 +1437,159 @@ function scoreCredentialUsage(providerRoot: string, provider: ProviderDefinition
 	);
 }
 
+// ---------------------------------------------------------------------------
+// sdk-owned-secret-presence (warn): provider-local double validation of
+// declared env secrets.
+//
+// The SDK runtime is the single source of truth for secret presence: declared
+// `required: true` secrets are validated before every handler/auth-flow
+// invocation and fail with the canonical structured MISSING_SECRET error
+// (HTTP 400, category credential_unavailable). Provider-local presence guards
+// (requireServiceKey/requireApiKey style) are dead weight that historically
+// diverged into inconsistent shapes (CONFIGURATION_ERROR vs MISSING_SECRET,
+// with/without category), which broke uniform incident attribution when nine
+// providers shipped with unprovisioned secrets (2026-07-22).
+//
+// Heuristic, warn-only: a line reading a declared `required: true` secret via
+// `.env.get(...)` (string literal or a const alias of a declared name)
+// followed within a small window by a falsy presence check plus a `throw`.
+// The rule flags duplication of the SDK gate ONLY: env names that are not
+// declared in defineProvider secrets[], and optional declarations
+// (`required: false`/omitted) that the runtime deliberately does not enforce,
+// are out of scope. Escape hatch:
+// `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+// ---------------------------------------------------------------------------
+
+const SDK_OWNED_SECRET_PRESENCE_RULE_ID = "sdk-owned-secret-presence";
+const SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES = 10;
+
+const ENV_GET_CALL_PATTERN =
+	/\.env\.get\(\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`|([A-Za-z_$][\w$]*))\s*\)/;
+
+const SECRET_ALIAS_CONST_PATTERN =
+	/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`)/g;
+
+const ENV_GET_ASSIGNMENT_PATTERN = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=[^;]*\.env\.get\(/;
+
+// Const aliases of declared secret names (e.g. `const SERVICE_KEY_ENV =
+// "APIFUSE__PROVIDER__X__SERVICE_KEY"`) so aliased `.env.get(SERVICE_KEY_ENV)`
+// guards are detected, not just direct string literals.
+function buildDeclaredSecretAliasMap(
+	providerRoot: string,
+	declaredNames: ReadonlySet<string>,
+): Map<string, string> {
+	const aliases = new Map<string, string>();
+	for (const filePath of listNonTestTypeScriptFiles(providerRoot)) {
+		const content = readFileSync(filePath, "utf8");
+		for (const match of content.matchAll(SECRET_ALIAS_CONST_PATTERN)) {
+			const alias = match[1];
+			const name = match[2] ?? match[3] ?? match[4];
+			if (alias && name && declaredNames.has(name)) {
+				aliases.set(alias, name);
+			}
+		}
+	}
+	return aliases;
+}
+
+function hasLocalSecretPresenceGuard(
+	line: string,
+	remainingLines: readonly string[],
+	declaredNames: ReadonlySet<string>,
+	aliases: ReadonlyMap<string, string>,
+): boolean {
+	const match = ENV_GET_CALL_PATTERN.exec(line);
+	if (!match) {
+		return false;
+	}
+	const literal = match[1] ?? match[2] ?? match[3];
+	const identifier = match[4];
+	const readsDeclaredSecret =
+		literal !== undefined
+			? declaredNames.has(literal)
+			: identifier !== undefined && aliases.has(identifier);
+	if (!readsDeclaredSecret) {
+		return false;
+	}
+
+	const window = [line, ...remainingLines.slice(0, SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES)];
+	if (!window.some((candidate) => /\bthrow\b/.test(candidate))) {
+		return false;
+	}
+
+	// Assigned read (`const key = ctx.env.get(...)`): only a falsy/undefined
+	// check on THAT variable counts as a presence guard. Anchoring on the
+	// assigned identifier avoids false positives from unrelated guards/throws
+	// that merely sit near the env read (mirrors the aliased runtime-guard rule).
+	const assigned = ENV_GET_ASSIGNMENT_PATTERN.exec(line)?.[1];
+	if (assigned) {
+		const escaped = assigned.replace(/\$/g, "\\$");
+		const guardPattern = new RegExp(
+			`(?:!\\s*${escaped}\\b|\\b${escaped}\\s*===?\\s*(?:undefined|null)\\b|\\b${escaped}\\s*==\\s*null\\b|\\b${escaped}(?:\\?\\.|\\.)length\\s*===?\\s*0\\b)`,
+		);
+		return window.some((candidate) => guardPattern.test(candidate));
+	}
+
+	// Un-assigned read: only an inline presence check on the same line counts,
+	// e.g. `if (!ctx.env.get(KEY)) throw ...`.
+	return /(?:if\s*\(\s*!|===?\s*undefined\b|==\s*null\b)/.test(line);
+}
+
+function scoreSdkOwnedSecretPresence(
+	providerRoot: string,
+	provider: ProviderDefinition,
+): SubmitCheck {
+	const passMessage = "Provider relies on SDK-owned secret presence validation.";
+	// Only `required: true` declarations: those are exactly what the runtime
+	// gate enforces. A presence guard over an optional secret is conditional
+	// business logic the SDK will not replace, not double validation.
+	const declaredNames: ReadonlySet<string> = new Set(
+		(provider.secrets ?? [])
+			.filter((secret) => secret.required === true)
+			.map((secret) => secret.name),
+	);
+	if (declaredNames.size === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const aliases = buildDeclaredSecretAliasMap(providerRoot, declaredNames);
+	const findings = findSourceFindings(providerRoot, (line, remainingLines) =>
+		hasLocalSecretPresenceGuard(line, remainingLines, declaredNames, aliases),
+	);
+	if (findings.length === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const { violations, overridden } = partitionAllowOverrides(
+		providerRoot,
+		findings,
+		SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+	);
+	if (violations.length === 0) {
+		return pass(
+			SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+			SDK_NATIVE_CATEGORY,
+			`${passMessage} ${overridden.length} acknowledged @apifuse-allow override(s).`,
+			0,
+			formatSourceFindings(overridden),
+		);
+	}
+
+	return {
+		id: SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+		category: SDK_NATIVE_CATEGORY,
+		level: "warn",
+		status: "warn",
+		points: 0,
+		maxPoints: 0,
+		message:
+			"Provider source re-validates declared env secret presence locally; the SDK owns this check.",
+		remediation:
+			"The provider SDK validates declared required secrets before handlers and auth flows run and returns the canonical MISSING_SECRET error (HTTP 400, category credential_unavailable). Declare the secret with required: true in defineProvider({ secrets: [...] }), delete the provider-local presence guard (requireServiceKey/requireApiKey style), and read the value directly with ctx.env.get(); the guard is dead weight and its divergent CONFIGURATION_ERROR-style shape is deprecated. Acknowledge intentional exceptions with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.",
+		evidence: formatSourceFindings(violations),
+	};
+}
+
 function findSourceLineMatches(
 	providerRoot: string,
 	pattern: RegExp | ((line: string) => boolean),
@@ -1523,6 +1689,10 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+// `.agents`/`.apifuse` stay IN scope on purpose: managed content there is
+// markdown/JSON (never scannable), while a planted `.ts`/`.sh` under those
+// directories must not become a scan-exempt hiding place for secrets, raw
+// fetch, or vendor imports.
 function shouldScanSourceDirectory(relativePath: string): boolean {
 	return ![".git", "node_modules", "dist", "build", "coverage"].includes(relativePath);
 }
@@ -1545,6 +1715,27 @@ function formatSourceFindings(findings: readonly SourceFinding[]): string[] {
 	return findings.map((finding) => `${finding.file}:${finding.line}`);
 }
 
+function scorePromptAssetFreshness(providerRoot: string): SubmitCheck {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return pass(
+			"prompt-assets-fresh",
+			"docs",
+			"SDK-managed agent prompt assets match the installed SDK version.",
+			0,
+		);
+	}
+
+	return blocker(
+		"prompt-assets-fresh",
+		"docs",
+		"SDK-managed agent prompt assets are missing, stale, or modified.",
+		"Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and .apifuse/prompt-assets.json for the installed SDK version.",
+		0,
+		formatPromptAssetIssues(verification),
+	);
+}
+
 function scoreRepositoryDx(providerRoot: string): SubmitCheck {
 	const missing: string[] = [];
 	if (!existsSync(resolve(providerRoot, ".gitignore"))) {

package/bin/apifuse-sync-assets.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+
+import {
+	formatPromptAssetIssues,
+	installedSdkVersion,
+	syncPromptAssets,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import { resolveProviderRoot } from "./apifuse-check.js";
+
+const HELP_TEXT = `Usage: apifuse sync-assets [path] [--check]
+Example: apifuse sync-assets .
+Default: apifuse sync-assets .
+
+Regenerates the SDK-managed agent prompt assets for the installed SDK version:
+AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and the
+.apifuse/prompt-assets.json manifest. Legacy top-level skills/ layouts are
+migrated. Idempotent.
+
+Options:
+  --check        Verify only; exit 1 with a diff list when assets are stale/missing/modified
+  --help, -h     Show this help`;
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	let checkOnly = false;
+	let inputPath: string | undefined;
+	for (const arg of args) {
+		if (arg === "--check") {
+			checkOnly = true;
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+		if (inputPath !== undefined) {
+			throw new Error(`Unexpected argument: ${arg}`);
+		}
+		inputPath = arg;
+	}
+
+	const providerRoot = resolveProviderRoot(inputPath ?? ".");
+
+	if (checkOnly) {
+		const verification = verifyPromptAssets(providerRoot);
+		if (verification.ok) {
+			console.log(
+				`Prompt assets are in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+			);
+			return;
+		}
+		console.error(`Prompt assets are out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error("\nRun `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate.");
+		process.exit(1);
+	}
+
+	const result = syncPromptAssets(providerRoot);
+
+	// Honesty gate: writes alone never imply success. sync-assets intentionally
+	// PRESERVES (does not delete) unauthorized skills and symlinks under
+	// .agents/skills, so it can return changed:false while verify still fails.
+	// Re-verify AFTER writing and let the true post-sync state drive the exit
+	// code — never claim success while the freshness gate would reject the tree.
+	const verification = verifyPromptAssets(providerRoot);
+
+	if (result.changed) {
+		for (const removed of result.removed) {
+			console.log(`removed  ${removed}`);
+		}
+		for (const wrote of result.wroteFiles) {
+			console.log(`wrote    ${wrote}`);
+		}
+		for (const link of result.createdSymlinks) {
+			console.log(`symlink  ${link}`);
+		}
+		console.log(`manifest ${result.manifestPath} (sdkVersion ${installedSdkVersion()})`);
+	}
+
+	if (!verification.ok) {
+		console.error(`\nPrompt assets are still out of sync in ${providerRoot}:`);
+		for (const issue of formatPromptAssetIssues(verification)) {
+			console.error(`  - ${issue}`);
+		}
+		console.error(
+			"\nsync-assets never deletes unrecognized content: resolve these by hand — remove any unauthorized skill directory or symlink under .agents/skills/, migrate a real .claude/.codex directory into .agents/ — then re-run `apifuse sync-assets .`.",
+		);
+		process.exit(1);
+	}
+
+	if (!result.changed) {
+		console.log(
+			`Prompt assets already in sync with the installed SDK (${installedSdkVersion()}): ${providerRoot}`,
+		);
+		return;
+	}
+	console.log(`\nPrompt assets synced: ${providerRoot}`);
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "sync-assets" ? argv.slice(1) : argv;
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/dist/auth-turn/index.d.ts

@@ -87,7 +87,7 @@ export declare const AUTH_TURN_SCHEMA: {
     };
     readonly $defs: {
         readonly completeTurnData: {
-            readonly title: 'Terminal payload for kind "complete"';
+            readonly title: "Terminal payload for kind \"complete\"";
             readonly description: "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.";
             readonly type: "object";
             readonly additionalProperties: true;
@@ -104,7 +104,7 @@ export declare const AUTH_TURN_SCHEMA: {
             };
         };
         readonly abortTurnData: {
-            readonly title: 'Terminal payload for kind "abort"';
+            readonly title: "Terminal payload for kind \"abort\"";
             readonly description: "data payload of an abort turn. code, when present, is the machine-readable abort reason.";
             readonly type: "object";
             readonly additionalProperties: true;

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;

package/dist/cli/commands.js

@@ -23,6 +23,13 @@ export const COMMAND_MANIFEST = {
         examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
         modulePath: "./apifuse-check",
     },
+    "sync-assets": {
+        name: "sync-assets",
+        summary: "Regenerate SDK-managed agent prompt assets (AGENTS.md, .agents/skills, symlinks, manifest) for the installed SDK version.",
+        usage: "apifuse sync-assets [path] [--check]",
+        examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
+        modulePath: "./apifuse-sync-assets",
+    },
     "submit-check": {
         name: "submit-check",
         summary: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -73,6 +80,7 @@ export const COMMAND_ORDER = [
     "create",
     "dev",
     "check",
+    "sync-assets",
     "submit-check",
     "record",
     "test",

package/dist/cli/create.d.ts

@@ -26,7 +26,10 @@ export type CreateResolvedOptions = {
 };
 export type ProviderPlanFile = {
     path: string;
+    /** File content, or the symlink target (relative path) for kind "symlink". */
     content: string;
+    /** Absent kind means "file" (backward compatible with older consumers). */
+    kind?: "file" | "symlink";
 };
 export type ProviderCreatePlan = {
     displayName: string;