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

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/bin/submit-check-delimited-text.ts

@@ -0,0 +1,50 @@
+const MIN_RECORDED_DELIMITED_TEXT_LENGTH = 200;
+const MIN_RECORDED_DELIMITED_TEXT_LINES = 3;
+const MAX_SAMPLED_DELIMITED_TEXT_LINES = 10;
+const DELIMITER_CANDIDATES = [",", "\t", ";"] as const;
+
+// Recognizes a recorded operation value that is a substantive tabular text
+// payload. The length floor and repeated, quote-aware field structure keep
+// short strings and prose from being treated as fixture provenance.
+export function hasSubstantiveDelimitedTextStructure(value: string): boolean {
+	if (value.length < MIN_RECORDED_DELIMITED_TEXT_LENGTH) {
+		return false;
+	}
+
+	const lines = value
+		.replace(/^\uFEFF/, "")
+		.split(/\r\n?|\n/)
+		.filter((line) => line.trim().length > 0);
+	if (lines.length < MIN_RECORDED_DELIMITED_TEXT_LINES) {
+		return false;
+	}
+
+	const sampledLines = lines.slice(0, MAX_SAMPLED_DELIMITED_TEXT_LINES);
+	return DELIMITER_CANDIDATES.some((delimiter) => {
+		const fieldCounts = sampledLines.map((line) => countDelimitedFields(line, delimiter));
+		const expectedFieldCount = fieldCounts[0];
+		return (
+			expectedFieldCount !== undefined &&
+			expectedFieldCount >= 2 &&
+			fieldCounts.every((fieldCount) => fieldCount === expectedFieldCount)
+		);
+	});
+}
+
+function countDelimitedFields(line: string, delimiter: string): number | undefined {
+	let fieldCount = 1;
+	let insideQuotes = false;
+	for (let index = 0; index < line.length; index += 1) {
+		const character = line[index];
+		if (character === '"') {
+			if (insideQuotes && line[index + 1] === '"') {
+				index += 1;
+			} else {
+				insideQuotes = !insideQuotes;
+			}
+		} else if (!insideQuotes && character === delimiter) {
+			fieldCount += 1;
+		}
+	}
+	return insideQuotes ? undefined : fieldCount;
+}

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

@@ -20,7 +20,7 @@ export declare const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped
@@ -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/auth-turn/index.js

@@ -18,7 +18,7 @@ export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schem
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped

package/dist/auth.d.ts

@@ -66,6 +66,20 @@ export interface DefineCredentialsAuthOptions<TFields extends CredentialsAuthFie
     /** Extra auth-flow context keys used by custom login/challenge code. */
     contextKeys?: readonly string[];
     login(ctx: FlowContext, input: CredentialsAuthInput<TFields>): CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string> | Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+    /**
+     * Optional re-mint of an expired session from the stored credential, wired
+     * to `auth.flow.refresh`.
+     *
+     * Credential-auth upstreams routinely invalidate a session well before the
+     * `expiresAt` the provider advertised, which leaves every operation failing
+     * with a reauth error until a human repeats the whole interactive login.
+     * Implement this to re-establish the session from what is already stored on
+     * the connection; the result is resolved exactly like `login`, so it may
+     * also raise a challenge when the upstream demands one. Omit it when the
+     * upstream has no non-interactive path and re-authentication genuinely
+     * requires the user.
+     */
+    refresh?(ctx: FlowContext, input: Partial<CredentialsAuthInput<TFields>>): CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string> | Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 export interface DefinedCredentialsAuth {
     auth: AuthConfig;

package/dist/auth.js

@@ -1,4 +1,5 @@
 import { AuthError, ProviderError } from "./errors.js";
+import { declarationInvalidError, DECLARATION_RULE_IDS, } from "./declaration-validation.js";
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
 const DEFAULT_ABORT_TURN_ID = "auth.abort";
@@ -198,6 +199,23 @@ function normalizeInput(fields, input) {
     }
     return result;
 }
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput(fields, input) {
+    const result = {};
+    for (const name of Object.keys(fields)) {
+        const value = input?.[name];
+        if (typeof value === "string") {
+            result[name] = value;
+        }
+    }
+    return result;
+}
 function assertCredentialKeys(credentialKeys, credential) {
     const missing = credentialKeys.filter((key) => {
         const value = credential[key];
@@ -379,6 +397,7 @@ export function defineCredentialsAuth(options) {
     const retryTurnId = options.retryTurnId ?? "credentials.retry";
     const completeTurnId = options.completeTurnId ?? "credentials.complete";
     const challenges = (options.challenges ?? {});
+    validateCredentialsAuthChallenges(challenges);
     return {
         auth: {
             mode: "credentials",
@@ -411,6 +430,27 @@ export function defineCredentialsAuth(options) {
                     }
                     return await pollPendingChallenge(ctx, options.credentialKeys, challenges, pending, completeTurnId);
                 },
+                // Only advertise refresh when the provider implements it: the
+                // protocol treats the hook's presence as "this connection can be
+                // re-established without the user", and exposing a stub that
+                // cannot actually re-mint would turn a recoverable expiry into a
+                // silent failure.
+                ...(options.refresh
+                    ? {
+                        refresh: async (ctx, rawInput) => {
+                            // A pending challenge belongs to the interactive flow that
+                            // raised it; finish it there rather than restarting.
+                            const pending = getPendingChallenge(ctx);
+                            if (pending) {
+                                return await continuePendingChallenge(ctx, options.credentialKeys, challenges, pending, rawInput, completeTurnId);
+                            }
+                            // Refresh runs without user input, so fields are optional
+                            // here — unlike `continue`, missing ones are not a retry.
+                            const result = await options.refresh(ctx, normalizePartialInput(options.fields, rawInput));
+                            return await resolveAuthResult(ctx, options.credentialKeys, challenges, result, completeTurnId);
+                        },
+                    }
+                    : {}),
             },
         },
         credential: {
@@ -425,3 +465,30 @@ export function defineCredentialsAuth(options) {
         },
     };
 }
+function validateCredentialsAuthChallenges(challenges) {
+    const violations = [];
+    for (const [challengeId, challenge] of Object.entries(challenges)) {
+        const fieldCount = challenge.fields && typeof challenge.fields === "object"
+            ? Object.keys(challenge.fields).length
+            : 0;
+        const fieldsDeclared = challenge.fields !== undefined && challenge.fields !== null;
+        const hasFields = fieldCount > 0;
+        const hasVerify = typeof challenge.verify === "function";
+        const hasPoll = typeof challenge.poll === "function";
+        const isInteractive = hasFields && hasVerify && !hasPoll;
+        const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+        const isHybrid = hasFields && hasVerify && hasPoll;
+        const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+        if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid))
+            continue;
+        const path = `challenges.${challengeId}`;
+        violations.push({
+            ruleId: DECLARATION_RULE_IDS.challengeShape,
+            path,
+            message: "challenge must be interactive, polling, or an explicit hybrid.",
+            fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+        });
+    }
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}

package/dist/ceremonies/index.d.ts

@@ -1,6 +1,16 @@
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
+export declare const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export declare const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export declare function defineAuthFlow<const TFlow extends AuthFlowDefinition>(flow: TFlow & AuthStartNoInputGuard<TFlow>): TFlow;
 export declare function createOAuth2Ceremony(options: {
     authorizeUrl: string;
     tokenUrl: string;
@@ -9,6 +19,12 @@ export declare function createOAuth2Ceremony(options: {
     scopes: string[];
     usePKCE?: boolean;
 }): AuthFlowDefinition;
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export declare function createOAuth2ProxiedStart(options: import("../types.js").ProxiedOAuthConfig): import("../types.js").AuthFlowStartHandler;
 export declare function createDeviceFlowCeremony(options: {
     deviceCodeUrl: string;
     tokenUrl: string;

package/dist/ceremonies/index.js

@@ -1,14 +1,17 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import Ajv2020 from "ajv/dist/2020.js";
 import { AUTH_TURN_SCHEMA } from "../auth-turn/index.js";
 import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors.js";
-const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
-// Runtime ceremony-output validation derives from the exported versioned
-// contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
-// dist/auth-turn/auth-turn.v1.schema.json, so the two cannot drift.
-const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+export const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
+const OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS = new Set([
+    "client_id",
+    "response_type",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+]);
 const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
@@ -17,6 +20,50 @@ const FORM_FIELD_ORDER_EXTENSION = "x-apifuse-field-order";
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function validateSchemaNode(value, schema, path, errors) {
+    if (schema.type === "object") {
+        if (!isRecord(value)) {
+            errors.push(`${path} must be object`);
+            return;
+        }
+        const properties = schema.properties ?? {};
+        for (const required of schema.required ?? []) {
+            if (!Object.hasOwn(value, required) || value[required] === undefined) {
+                errors.push(`${path} must have required property '${required}'`);
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(value)) {
+                if (!Object.hasOwn(properties, key)) {
+                    errors.push(`${path} must NOT have additional property '${key}'`);
+                }
+            }
+        }
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (Object.hasOwn(value, key) && value[key] !== undefined) {
+                validateSchemaNode(value[key], childSchema, `${path}/${key}`, errors);
+            }
+        }
+        return;
+    }
+    if (schema.type === "string") {
+        if (typeof value !== "string") {
+            errors.push(`${path} must be string`);
+        }
+        else if (schema.minLength !== undefined && value.length < schema.minLength) {
+            errors.push(`${path} must NOT have fewer than ${schema.minLength} characters`);
+        }
+        return;
+    }
+    if (schema.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+            errors.push(`${path} must be number`);
+        }
+        else if (schema.minimum !== undefined && value < schema.minimum) {
+            errors.push(`${path} must be >= ${schema.minimum}`);
+        }
+    }
+}
 function ensureRecord(value) {
     return isRecord(value) ? value : {};
 }
@@ -105,16 +152,28 @@ function withDeclaredFormFieldOrder(expectedInput) {
     };
 }
 export function validateCeremonyOutput(turn) {
-    if (!validateAuthTurn(turn)) {
-        const detail = validateAuthTurn.errors
-            ?.map((error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`)
-            .join("; ");
-        throw new TurnValidationError(detail || "Invalid AuthTurn output");
+    // Evaluate the exact exported versioned schema without eagerly initializing
+    // a general-purpose JSON Schema compiler in every provider process. Contract
+    // parity tests compare this focused evaluator with AJV over all fixtures and
+    // edge probes, so the runtime and shipped document remain locked together.
+    const errors = [];
+    validateSchemaNode(turn, AUTH_TURN_SCHEMA, "", errors);
+    if (errors.length > 0) {
+        throw new TurnValidationError(errors.join("; "));
     }
     return turn;
 }
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow(flow) {
+    return flow;
+}
 export function createOAuth2Ceremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
             getRequiredEnv(ctx, options.clientSecretEnvKey);
@@ -171,10 +230,58 @@ export function createOAuth2Ceremony(options) {
             });
         }, "OAuth token exchange failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-    };
+    });
+}
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export function createOAuth2ProxiedStart(options) {
+    const pkce = options.pkce ?? "S256";
+    return (ctx) => runCeremonyHandler(async () => {
+        for (const key of Object.keys(options.authorizeParams ?? {})) {
+            if (OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+                throw new ValidationError(`OAuth2 proxied authorizeParams cannot override reserved parameter "${key}".`);
+            }
+        }
+        const proxyOrigin = ctx.env.get(OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY);
+        if (!proxyOrigin) {
+            throw new ProviderSecretError(`Missing required platform environment: ${OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY}`);
+        }
+        const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+        if (!ctx.flowId) {
+            throw new ValidationError("OAuth2 proxied start requires the gateway flow id.");
+        }
+        const authorizePath = new URL(options.authorizeUrl).pathname;
+        const url = new URL(`/p/${encodeURIComponent(ctx.providerId)}/f/${encodeURIComponent(ctx.flowId)}${authorizePath}`, proxyOrigin);
+        url.searchParams.set("client_id", clientId);
+        url.searchParams.set("response_type", "code");
+        if (pkce === "S256") {
+            const verifier = createCodeVerifier();
+            ctx.context.set(OAUTH2_PROXIED_PKCE_VERIFIER_KEY, verifier);
+            url.searchParams.set("code_challenge", createCodeChallenge(verifier));
+            url.searchParams.set("code_challenge_method", "S256");
+        }
+        for (const [key, value] of Object.entries(options.authorizeParams ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        return createTurn("redirect", {
+            data: { url: url.toString() },
+            hint: "Open the provider authorization page to continue.",
+            expectedInput: {
+                type: "object",
+                required: ["code", "state"],
+                properties: {
+                    code: { type: "string" },
+                    state: { type: "string" },
+                },
+            },
+        });
+    }, "OAuth2 proxied start failed", ctx);
 }
 export function createDeviceFlowCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const response = await ctx.http.post(options.deviceCodeUrl, {
                 client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
@@ -232,10 +339,10 @@ export function createDeviceFlowCeremony(options) {
             });
         }, "Device flow polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-    };
+    });
 }
 export function createWebAuthnCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: (ctx) => runCeremonyHandler(async () => {
             const challenge = toBase64Url(randomBytes(32));
             ctx.context.set("__webauthn_challenge", challenge);
@@ -277,21 +384,23 @@ export function createWebAuthnCeremony(options) {
             });
         }, "WebAuthn verification failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-    };
+    });
 }
 export function createMagicLinkCeremony(options) {
     const emailField = options.emailField ?? "email";
-    return {
-        start: (ctx, input = {}) => runCeremonyHandler(async () => {
+    const buildEmailForm = () => buildJsonSchemaForm({
+        type: "object",
+        required: [emailField],
+        properties: {
+            [emailField]: { type: "string", format: "email" },
+        },
+    }, "Provide the email address to receive a magic link.");
+    return defineAuthFlow({
+        start: (ctx) => runCeremonyHandler(async () => buildEmailForm(), "Magic link start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const email = getString(input, emailField);
             if (!email) {
-                return buildJsonSchemaForm({
-                    type: "object",
-                    required: [emailField],
-                    properties: {
-                        [emailField]: { type: "string", format: "email" },
-                    },
-                }, "Provide the email address to receive a magic link.");
+                return buildEmailForm();
             }
             await ctx.http.post(options.sendUrl, { email });
             ctx.context.set(MAGIC_LINK_KEY, {
@@ -303,11 +412,7 @@ export function createMagicLinkCeremony(options) {
                 hint: "Check your email for the magic link, then poll for completion.",
                 timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
             });
-        }, "Magic link start failed", ctx, input),
-        continue: async () => validateCeremonyOutput(createTurn("poll", {
-            hint: "Continue polling for magic link completion.",
-            timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
-        })),
+        }, "Magic link continuation failed", ctx, input),
         poll: (ctx) => runCeremonyHandler(async () => {
             const state = getNestedRecord(ctx, MAGIC_LINK_KEY);
             const email = getString(state, "email");
@@ -333,10 +438,10 @@ export function createMagicLinkCeremony(options) {
             });
         }, "Magic link polling failed", ctx),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-    };
+    });
 }
 export function createFormCeremony(options) {
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const { prevalidate } = await import("../runtime/prevalidate.js");
@@ -354,7 +459,7 @@ export function createFormCeremony(options) {
             });
         }, "Form submission failed", ctx, input),
         abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-    };
+    });
 }
 export function combineCeremonies(...ceremonies) {
     function getStage(ctx) {
@@ -406,7 +511,7 @@ export function combineCeremonies(...ceremonies) {
 }
 export function createSwitchCeremony(options) {
     const choiceKeys = Object.keys(options.choices);
-    return {
+    return defineAuthFlow({
         start: async () => validateCeremonyOutput(createTurn("multi_choice", {
             data: { choices: choiceKeys },
             hint: options.prompt ?? "Choose an authentication method.",
@@ -452,5 +557,5 @@ export function createSwitchCeremony(options) {
             }
             return createTurn("abort", { hint: "Switch ceremony aborted." });
         }, "Switch ceremony abort failed", ctx),
-    };
+    });
 }

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" | "migrate-shape" | "migrate-operation-declaration" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;

package/dist/cli/commands.js

@@ -23,6 +23,30 @@ 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",
+    },
+    "migrate-shape": {
+        name: "migrate-shape",
+        summary: "Migrate a provider to the phase-separated SDK: two-phase defineProvider in index.ts and curried defineOperation across sources.",
+        usage: "apifuse migrate-shape [path] [--check] [--json]",
+        examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
+        modulePath: "./apifuse-migrate-shape",
+    },
+    "migrate-operation-declaration": {
+        name: "migrate-operation-declaration",
+        summary: "Migrate legacy nested operation declarations to the ADR-0009 flat shape, refusing ambiguous safety or metadata.",
+        usage: "apifuse migrate-operation-declaration [path] [--check] [--json]",
+        examples: [
+            "apifuse migrate-operation-declaration .",
+            "apifuse migrate-operation-declaration . --check --json",
+        ],
+        modulePath: "./apifuse-migrate-operation-declaration",
+    },
     "submit-check": {
         name: "submit-check",
         summary: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -73,6 +97,9 @@ export const COMMAND_ORDER = [
     "create",
     "dev",
     "check",
+    "sync-assets",
+    "migrate-shape",
+    "migrate-operation-declaration",
     "submit-check",
     "record",
     "test",