feat(sdk): add scoped managed resource creation

Author: chenanran555

.changeset/calm-otters-list.md

@@ -2,4 +2,4 @@
 "@openagentpack/sdk": minor
 ---
 
-Expose Bailian Managed Agents operation-level reads, cursor pagination, session events, file downloads, deployment actions, provider capability metadata, address-scoped Agent planning/apply with create-only safety, and Agent display names independent from logical YAML keys.
+Expose Bailian Managed Agents operation-level reads, cursor pagination, session events, file downloads, deployment actions, provider capability metadata, generic scoped create-only planning/apply, local Skill source inspection, scoped Vault Credential creation, and display names independent from logical YAML keys.

packages/sdk/src/index.ts

@@ -23,7 +23,15 @@ export {
 	writeProjectRuntime,
 } from "./internal/core/project-runtime.ts";
 
-export type { ResolvedProjectConfig } from "./internal/types/config.ts";
+export type {
+	CredentialDecl,
+	DeploymentDecl,
+	EnvironmentDecl,
+	ProjectConfig,
+	ResolvedProjectConfig,
+	SkillDecl,
+	VaultDecl,
+} from "./internal/types/config.ts";
 export type { LoadedProjectConfig } from "./internal/parser/index.ts";
 export {
 	resolveProjectConfig,
@@ -46,6 +54,7 @@ export type {
 	ResourcePlanScope,
 	ResourceRefreshResult,
 	ResourceRuntimeOptions,
+	ResourceSyncMode,
 	ResourceSyncRun,
 } from "./internal/core/resource-runtime.ts";
 
@@ -142,8 +151,21 @@ export type {
 	SkillVersionPage,
 	VaultListOptions,
 	VaultPage,
+	VaultCredentialInfo,
 } from "./internal/types/managed-api.ts";
 
+export {
+	createVaultCredential,
+	createVaultCredentialWithStateBackend,
+	planVaultCredentialCreate,
+	planVaultCredentialCreateWithStateBackend,
+} from "./internal/core/vault-credential-runtime.ts";
+export type {
+	VaultCredentialCreateOptions,
+	VaultCredentialCreatePlan,
+	VaultCredentialCreateResult,
+} from "./internal/core/vault-credential-runtime.ts";
+
 export type {
 	DestroyDefaultMemoryStoreResult,
 	DestroyResourceResult,
@@ -288,6 +310,8 @@ export { LocalFileStateBackend } from "./internal/state/local-file-state-backend
 export type { StateScope } from "./internal/state/backend.ts";
 
 export { extractSkillZipFiles } from "./internal/utils/normalize-skill-zip.ts";
+export { inspectSkillSource } from "./internal/core/skill-source.ts";
+export type { SkillSourceInspection } from "./internal/core/skill-source.ts";
 
 export type {
 	RuntimeFeedbackEvent,

packages/sdk/src/internal/core/agent-runtime.ts

@@ -30,7 +30,7 @@ import {
 	planProjectContext,
 	type ResourceExecutionResult,
 	type ResourcePlanResult,
-	replaceResourcePlan,
+	type ResourceSyncMode,
 	selectDestructive,
 } from "./resource-runtime.ts";
 
@@ -61,7 +61,7 @@ export interface AgentResourcePlanOptions {
 	mode?: AgentResourceSyncMode;
 }
 
-export type AgentResourceSyncMode = "reconcile" | "create-only";
+export type AgentResourceSyncMode = ResourceSyncMode;
 
 export interface AgentResourceSyncOptions extends AgentResourcePlanOptions {
 	policy?: DestructivePolicy;
@@ -251,29 +251,15 @@ export async function planAgentResources(
 ): Promise<AgentResourcePlan> {
 	const agent = getAgent(ctx, agentId);
 	const rootAddress = collectAgentAddresses(ctx.config, agent.agentName, agent.provider)[0]!;
-	let planned = await planProjectContext(ctx, {
+	const planned = await planProjectContext(ctx, {
 		provider: agent.provider,
 		scope: { roots: [rootAddress] },
+		mode: options.mode,
 		refresh: options.refresh,
 		quiet: options.quiet ?? true,
 	});
 	const actions = planned.plan.actions;
-	let diagnostics = planned.plan.diagnostics;
-	if (options.mode === "create-only") {
-		const blockedReason = getCreateOnlyBlockedReason(planned, rootAddress);
-		if (blockedReason) {
-			diagnostics = [
-				...diagnostics,
-				{
-					severity: "error",
-					code: "agent.create_only.blocked",
-					message: blockedReason,
-					resource: rootAddress,
-				},
-			];
-			planned = replaceResourcePlan(planned, { ...planned.plan, diagnostics });
-		}
-	}
+	const diagnostics = planned.plan.diagnostics;
 	return {
 		agentId,
 		provider: agent.provider,
@@ -386,29 +372,6 @@ export async function syncAgentResourcesWithStateBackend(
 	return writeProjectRuntime(input, (ctx) => syncAgentResources(ctx, agentId, options));
 }
 
-function getCreateOnlyBlockedReason(planned: ResourcePlanResult, rootAddress: ResourceAddress): string | undefined {
-	const refreshError = planned.refreshResult?.errors[0];
-	if (refreshError) {
-		return `Cannot verify Agent dependencies because refresh failed for ${addressKey(refreshError.resource.address)}: ${refreshError.error}`;
-	}
-
-	const rootKey = addressKey(rootAddress);
-	const rootAction = planned.plan.actions.find((action) => addressKey(action.address) === rootKey);
-	if (!rootAction) return `Scoped plan did not contain the target Agent ${rootKey}.`;
-	if (rootAction.action !== "create") {
-		return `Target Agent ${rootKey} must be a new resource, but the scoped plan requires '${rootAction.action}'.`;
-	}
-
-	const dependencyChanges = planned.plan.actions.filter(
-		(action) => addressKey(action.address) !== rootKey && action.action !== "no-op",
-	);
-	if (dependencyChanges.length > 0) {
-		const labels = dependencyChanges.map((action) => `${addressKey(action.address)} (${action.action})`).join(", ");
-		return `Agent create requires every declared dependency to be up-to-date. Reconcile these resources first: ${labels}.`;
-	}
-	return undefined;
-}
-
 export function toAgentSyncResults(execution: ResourceExecutionResult): AgentSyncResult[] {
 	return execution.results.map((result) => ({
 		action: result.action,

packages/sdk/src/internal/core/managed-api-runtime.ts

@@ -312,21 +312,27 @@ const UNSUPPORTED_OAUTH: ManagedAgentOperationCapability = {
 };
 
 const BAILIAN_OPERATIONS: Record<string, ManagedAgentOperationCapability> = {
+	"agent.create": { ...API_KEY, reason: "YAML declaration plus scoped create-only apply." },
 	"agent.list": API_KEY,
 	"agent.get": API_KEY,
 	"agent.search": CLIENT_SEARCH,
 	"agent.versions": API_KEY,
+	"environment.create": { ...API_KEY, reason: "YAML declaration plus scoped create-only apply." },
 	"environment.list": API_KEY,
 	"environment.get": API_KEY,
 	"environment.search": CLIENT_SEARCH,
+	"skill.create": { ...API_KEY, reason: "YAML declaration plus scoped create-only apply." },
 	"skill.list": API_KEY,
 	"skill.get": API_KEY,
 	"skill.search": CLIENT_SEARCH,
 	"skill.versions": API_KEY,
 	"skill.download": API_KEY,
+	"vault.create": { ...API_KEY, reason: "YAML declaration plus scoped create-only apply." },
+	"vault.credential.create": { ...API_KEY, reason: "YAML declaration plus scoped Vault transaction." },
 	"vault.list": API_KEY,
 	"vault.get": API_KEY,
 	"vault.search": CLIENT_SEARCH,
+	"deployment.create": { ...API_KEY, reason: "YAML declaration plus scoped create-only apply." },
 	"deployment.list": API_KEY,
 	"deployment.get": API_KEY,
 	"deployment.search": { ...API_KEY, reason: "Maps to the server-side keyword parameter." },

packages/sdk/src/internal/core/resource-runtime.ts

@@ -17,12 +17,15 @@ import { readProjectRuntime, writeProjectRuntime } from "./project-runtime.ts";
 export interface ResourceRuntimeOptions extends DestructiveDecisionOptions {
 	provider?: string;
 	scope?: ResourcePlanScope;
+	mode?: ResourceSyncMode;
 	refresh?: boolean;
 	refreshOnly?: boolean;
 	quiet?: boolean;
 	onFeedback?: RuntimeFeedbackSink;
 }
 
+export type ResourceSyncMode = "reconcile" | "create-only";
+
 export interface ResourcePlanScope {
 	roots: ResourceAddress[];
 	includeDependencies?: boolean;
@@ -51,6 +54,7 @@ export interface ResourcePlanResult {
 	targetProviders?: string[];
 	destructiveActions: PlannedAction[];
 	selectedAddresses?: ResourceAddress[];
+	mode?: ResourceSyncMode;
 }
 
 export type DestructivePolicy = "block" | "prompt" | "force";
@@ -81,6 +85,10 @@ export async function syncProjectResourcesWithStateBackend(
 		if (options.refreshOnly) {
 			return { planned };
 		}
+		if (options.mode === "create-only") {
+			const errorDiagnostic = planned.plan.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+			if (errorDiagnostic) throw new UserError(errorDiagnostic.message);
+		}
 		return {
 			planned,
 			execution: await executePlannedProject(planned, {
@@ -173,6 +181,9 @@ export async function planProjectContext(
 	ctx: ProjectRuntimeContext,
 	options: ResourceRuntimeOptions = {},
 ): Promise<ResourcePlanResult> {
+	if (options.mode === "create-only" && !options.scope) {
+		throw new UserError("Resource create-only mode requires an explicit resource scope.");
+	}
 	let targetProviders = resolveTargetProviders(options.provider);
 	if (!targetProviders && options.scope) {
 		targetProviders = [...new Set(options.scope.roots.map((root) => root.provider))];
@@ -190,11 +201,14 @@ export async function planProjectContext(
 				})
 			: undefined;
 
-	const plan = await buildPlan(ctx.config, ctx.state.getStateFile(), {
+	let plan = await buildPlan(ctx.config, ctx.state.getStateFile(), {
 		providers: targetProviders,
 		configPath: ctx.configPath,
 		resourceAddresses: selectedAddresses,
 	});
+	if (options.mode === "create-only" && options.scope) {
+		plan = enforceCreateOnlyPlan(plan, options.scope, toResourceRefreshResult(refreshResult));
+	}
 
 	return {
 		executionContext: ctx,
@@ -203,6 +217,54 @@ export async function planProjectContext(
 		targetProviders,
 		destructiveActions: selectDestructive(plan.actions),
 		selectedAddresses,
+		mode: options.mode,
+	};
+}
+
+function enforceCreateOnlyPlan(
+	plan: ExecutionPlan,
+	scope: ResourcePlanScope,
+	refreshResult: ResourceRefreshResult | undefined,
+): ExecutionPlan {
+	const reasons: string[] = [];
+	const rootKeys = new Set(scope.roots.map(addressKey));
+	const refreshError = refreshResult?.errors[0];
+	if (refreshError) {
+		reasons.push(
+			`Cannot verify scoped dependencies because refresh failed for ${addressKey(refreshError.resource.address)}: ${refreshError.error}`,
+		);
+	}
+
+	for (const root of scope.roots) {
+		const rootKey = addressKey(root);
+		const rootAction = plan.actions.find((action) => addressKey(action.address) === rootKey);
+		if (!rootAction) {
+			reasons.push(`Scoped plan did not contain target resource ${rootKey}.`);
+		} else if (rootAction.action !== "create") {
+			reasons.push(`Target resource ${rootKey} must be new, but the scoped plan requires '${rootAction.action}'.`);
+		}
+	}
+
+	const dependencyChanges = plan.actions.filter(
+		(action) => !rootKeys.has(addressKey(action.address)) && action.action !== "no-op",
+	);
+	if (dependencyChanges.length > 0) {
+		const labels = dependencyChanges.map((action) => `${addressKey(action.address)} (${action.action})`).join(", ");
+		reasons.push(`Create-only requires every scoped dependency to be up-to-date. Reconcile first: ${labels}.`);
+	}
+
+	if (reasons.length === 0) return plan;
+	return {
+		...plan,
+		diagnostics: [
+			...plan.diagnostics,
+			{
+				severity: "error",
+				code: "resource.create_only.blocked",
+				message: reasons.join(" "),
+				resource: scope.roots[0],
+			},
+		],
 	};
 }
 

packages/sdk/src/internal/core/skill-source.ts

@@ -0,0 +1,71 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { parse } from "yaml";
+import { UserError } from "../errors.ts";
+import type { SkillFile } from "../types/skill-file.ts";
+import { collectFiles } from "../utils/collect-files.ts";
+import { extractSkillZipFiles } from "../utils/normalize-skill-zip.ts";
+
+export interface SkillSourceInspection {
+	name: string;
+	sourcePath: string;
+	files: SkillFile[];
+}
+
+/** Inspect and normalize a local Skill directory, zip, or single SKILL.md. */
+export async function inspectSkillSource(
+	source: string,
+	options: { basePath?: string } = {},
+): Promise<SkillSourceInspection> {
+	if (/^https?:\/\//i.test(source)) {
+		throw new UserError("Skill source inspection only accepts a local directory, zip, or SKILL.md file.");
+	}
+	const sourcePath = resolve(options.basePath ?? process.cwd(), source);
+	const sourceStat = statSync(sourcePath, { throwIfNoEntry: false });
+	if (!sourceStat) throw new UserError(`Skill source not found: ${source}`);
+
+	let files: SkillFile[];
+	if (sourceStat.isDirectory()) {
+		files = collectFiles(sourcePath, "");
+	} else if (sourceStat.isFile() && sourcePath.toLowerCase().endsWith(".zip")) {
+		files = await extractSkillZipFiles(readFileSync(sourcePath));
+	} else if (sourceStat.isFile() && basename(sourcePath).toLowerCase() === "skill.md") {
+		files = [{ relativePath: "SKILL.md", content: readFileSync(sourcePath) }];
+	} else {
+		throw new UserError("Skill source must be a directory, .zip archive, or SKILL.md file.");
+	}
+
+	const normalizedFiles = normalizeSkillRoot(files);
+	const manifest = normalizedFiles.find((file) => file.relativePath === "SKILL.md")!;
+	const name = parseSkillManifestName(manifest.content);
+	return { name, sourcePath, files: normalizedFiles };
+}
+
+function normalizeSkillRoot(files: SkillFile[]): SkillFile[] {
+	if (files.some((file) => file.relativePath === "SKILL.md")) return files;
+	const manifests = files.filter((file) => file.relativePath.endsWith("/SKILL.md"));
+	if (manifests.length === 0) throw new UserError("Skill source does not contain SKILL.md.");
+	if (manifests.length > 1) {
+		throw new UserError("Skill source contains multiple SKILL.md files and has no unambiguous root.");
+	}
+	const prefix = manifests[0]!.relativePath.slice(0, -"SKILL.md".length);
+	return files
+		.filter((file) => file.relativePath.startsWith(prefix))
+		.map((file) => ({ ...file, relativePath: file.relativePath.slice(prefix.length) }));
+}
+
+function parseSkillManifestName(content: Buffer): string {
+	const text = content.toString("utf8");
+	const frontmatter = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\s*\r?\n|$)/);
+	if (!frontmatter) throw new UserError("SKILL.md must start with YAML frontmatter containing a name.");
+	let manifest: unknown;
+	try {
+		manifest = parse(frontmatter[1]!);
+	} catch (error) {
+		throw new UserError(`Invalid SKILL.md frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const rawName = manifest && typeof manifest === "object" ? (manifest as Record<string, unknown>).name : undefined;
+	const name = typeof rawName === "string" ? rawName.trim() : "";
+	if (!name) throw new UserError("SKILL.md frontmatter must contain a non-empty name.");
+	return name;
+}