feat(sdk): support scoped create-only agent sync

Add address-scoped planning, refresh, and execution for Agent resources.
Require the target Agent to be newly created and all dependencies to be
reconciled, while keeping display names independent from YAML keys.

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, and provider capability metadata.
+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.

packages/sdk/src/index.ts

@@ -34,6 +34,7 @@ export {
 	decideDestructive,
 	executePlannedProject,
 	importResource,
+	planProjectWithStateBackend,
 	planProjectContext,
 	syncProjectResourcesWithStateBackend,
 } from "./internal/core/resource-runtime.ts";
@@ -42,6 +43,7 @@ export type {
 	ResourceActionResult,
 	ResourceExecutionResult,
 	ResourcePlanResult,
+	ResourcePlanScope,
 	ResourceRefreshResult,
 	ResourceRuntimeOptions,
 	ResourceSyncRun,
@@ -209,8 +211,16 @@ export {
 	listCloudAgents,
 	listCloudEnvironments,
 	listCloudVaults,
+	planAgentResources,
+	planAgentResourcesWithStateBackend,
 	syncAgentResourcesWithStateBackend,
 } from "./internal/core/agent-runtime.ts";
+export type {
+	AgentResourcePlan,
+	AgentResourcePlanOptions,
+	AgentResourceSyncMode,
+	AgentResourceSyncOptions,
+} from "./internal/core/agent-runtime.ts";
 
 export type { CollectedSessionEvents } from "./internal/core/session-runtime.ts";
 export {

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

@@ -20,6 +20,7 @@ export interface AgentMcpBuildInput {
 }
 
 export interface AgentBuildInput {
+	name?: string;
 	description?: string;
 	model?: AgentDecl["model"];
 	instructions?: string;
@@ -79,6 +80,7 @@ export function buildAgentDecl(base: AgentDecl | undefined, input: AgentBuildInp
 
 	const agent: AgentDecl = {
 		...(base ?? {}),
+		name: input.name ?? base?.name,
 		description: input.description ?? base?.description,
 		model,
 		instructions: input.instructions ?? base?.instructions ?? "",

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

@@ -1,4 +1,5 @@
 import { UserError } from "../errors.ts";
+import { buildDependencyGraph, collectDependencyClosure } from "../graph/dependency.ts";
 import type { RemoteResource } from "../providers/interface.ts";
 import type { ResourceCrudAdapter } from "../providers/resource-workflow.ts";
 import { buildSessionBindings, resolveSessionProvider } from "../session/session-manager.ts";
@@ -21,7 +22,7 @@ import type { ResourceAddress } from "../types/state.ts";
 import { addressKey } from "../types/state.ts";
 import { resolveAgentMaterialization } from "./agent-materialization.ts";
 import type { BackendRuntimeInput, ProjectRuntimeContext } from "./project-runtime.ts";
-import { getRuntimeProvider, writeProjectRuntime } from "./project-runtime.ts";
+import { getRuntimeProvider, readProjectRuntime, writeProjectRuntime } from "./project-runtime.ts";
 import {
 	type DestructivePolicy,
 	decideDestructive,
@@ -57,8 +58,11 @@ export interface AgentResourcePlan {
 export interface AgentResourcePlanOptions {
 	refresh?: boolean;
 	quiet?: boolean;
+	mode?: AgentResourceSyncMode;
 }
 
+export type AgentResourceSyncMode = "reconcile" | "create-only";
+
 export interface AgentResourceSyncOptions extends AgentResourcePlanOptions {
 	policy?: DestructivePolicy;
 	confirm?: (actions: PlannedAction[]) => boolean | Promise<boolean>;
@@ -246,22 +250,48 @@ export async function planAgentResources(
 	options: AgentResourcePlanOptions = {},
 ): Promise<AgentResourcePlan> {
 	const agent = getAgent(ctx, agentId);
-	const planned = await planProjectContext(ctx, {
+	const rootAddress = collectAgentAddresses(ctx.config, agent.agentName, agent.provider)[0]!;
+	let planned = await planProjectContext(ctx, {
 		provider: agent.provider,
+		scope: { roots: [rootAddress] },
 		refresh: options.refresh,
 		quiet: options.quiet ?? true,
 	});
-	const actions = filterAgentActions(ctx, agent, planned.plan);
+	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 });
+		}
+	}
 	return {
 		agentId,
 		provider: agent.provider,
 		actions,
-		diagnostics: filterAgentDiagnostics(ctx, agent, planned.plan),
+		diagnostics,
 		destructiveActions: selectDestructive(actions),
 		planned,
 	};
 }
 
+export async function planAgentResourcesWithStateBackend(
+	input: BackendRuntimeInput,
+	agentId: string,
+	options: AgentResourcePlanOptions = {},
+): Promise<AgentResourcePlan> {
+	return readProjectRuntime(input, (ctx) => planAgentResources(ctx, agentId, options));
+}
+
 export async function syncAgentResources(
 	ctx: ProjectRuntimeContext,
 	agentId: string,
@@ -278,6 +308,7 @@ async function runAgentSync(
 	const fullPlan = await planAgentResources(ctx, agentId, {
 		refresh: options.refresh,
 		quiet: options.quiet,
+		mode: options.mode,
 	});
 	const actions = fullPlan.actions;
 	const destructiveActions = fullPlan.destructiveActions;
@@ -317,11 +348,7 @@ async function runAgentSync(
 	}
 
 	try {
-		const scopedPlan = {
-			diagnostics: fullPlan.diagnostics,
-			actions: scopePlanActions(fullPlan.planned.plan, actions),
-		};
-		const execution = await executePlannedProject(replaceResourcePlan(fullPlan.planned, scopedPlan), {
+		const execution = await executePlannedProject(fullPlan.planned, {
 			policy: "force",
 		});
 		const results = toAgentSyncResults(execution);
@@ -359,6 +386,29 @@ 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,
@@ -443,36 +493,6 @@ export function getAgentReadinessFromPlan(
 	};
 }
 
-function filterAgentActions(ctx: ProjectRuntimeContext, agent: AgentDefinition, plan: ExecutionPlan): PlannedAction[] {
-	const relevantKeys = agentAddressKeys(ctx, agent);
-	return plan.actions.filter(
-		(action) =>
-			relevantKeys.has(addressKey(action.address)) ||
-			action.dependencies.some((dependency) => relevantKeys.has(addressKey(dependency))),
-	);
-}
-
-function filterAgentDiagnostics(ctx: ProjectRuntimeContext, agent: AgentDefinition, plan: ExecutionPlan): Diagnostic[] {
-	const relevantKeys = agentAddressKeys(ctx, agent);
-	return plan.diagnostics.filter(
-		(diagnostic) => !diagnostic.resource || relevantKeys.has(addressKey(diagnostic.resource)),
-	);
-}
-
-function agentAddressKeys(ctx: ProjectRuntimeContext, agent: AgentDefinition): Set<string> {
-	return new Set(collectAgentAddresses(ctx.config, agent.agentName, agent.provider).map(addressKey));
-}
-
-function scopePlanActions(fullPlan: ExecutionPlan, agentActions: PlannedAction[]): PlannedAction[] {
-	const allowedKeys = new Set(agentActions.filter((action) => action.action !== "no-op").map(actionKey));
-	return fullPlan.actions.filter((action) => action.action === "no-op" || allowedKeys.has(actionKey(action)));
-}
-
-function actionKey(action: PlannedAction): string {
-	const address = action.address;
-	return `${action.action}:${address.provider}:${address.type}:${address.name}`;
-}
-
 function isNonBlockingAgentDrift(action: PlannedAction): boolean {
 	if (action.action === "no-op") return true;
 	return action.readinessImpact === "non_blocking";
@@ -485,35 +505,13 @@ export function collectAgentAddresses(config: ProjectConfig, agentName: string,
 	}
 	const resolvedProvider = provider ?? resolveSessionProvider(agentName, config, undefined);
 	const materialization = resolveAgentMaterialization(resolvedProvider, agent);
-	const addresses: ResourceAddress[] = [
-		{ type: materialization.resourceType, name: agentName, provider: resolvedProvider },
-	];
-
-	if (agent.environment) {
-		addresses.push({
-			type: "environment",
-			name: agent.environment,
-			provider: resolvedProvider,
-		});
-	}
-	if (agent.vault) {
-		addresses.push({ type: "vault", name: agent.vault, provider: resolvedProvider });
-	}
-	for (const name of agent.memory_stores ?? []) {
-		addresses.push({ type: "memory_store", name, provider: resolvedProvider });
-	}
-	for (const skill of agent.skills ?? []) {
-		if (typeof skill === "string") {
-			addresses.push({ type: "skill", name: skill, provider: resolvedProvider });
-		}
-	}
-	for (const subAgent of agent.multiagent?.agents ?? []) {
-		const subDecl = config.agents?.[subAgent];
-		const subType = subDecl ? resolveAgentMaterialization(resolvedProvider, subDecl).resourceType : "agent";
-		addresses.push({ type: subType, name: subAgent, provider: resolvedProvider });
-	}
-
-	return addresses;
+	const rootAddress: ResourceAddress = {
+		type: materialization.resourceType,
+		name: agentName,
+		provider: resolvedProvider,
+	};
+	const graph = buildDependencyGraph(config, [resolvedProvider]);
+	return collectDependencyClosure(graph, [rootAddress]);
 }
 
 function toAgentDefinition(config: ProjectConfig, agentName: string, agent: AgentDecl): AgentDefinition {

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

@@ -1,5 +1,6 @@
 import { UserError } from "../errors.ts";
 import { type ExecutionResult, executePlan } from "../executor/executor.ts";
+import { buildDependencyGraph, collectDependencyClosure } from "../graph/dependency.ts";
 import { getResourceDeclaration } from "../planner/declaration.ts";
 import { buildReadinessBaseline } from "../planner/plan-semantics.ts";
 import { buildPlan } from "../planner/planner.ts";
@@ -8,18 +9,25 @@ import { readComparableIfSupported } from "../providers/drift-support.ts";
 import type { ExecutionPlan, PlannedAction } from "../types/plan.ts";
 import type { RuntimeFeedbackSink } from "../types/runtime-feedback.ts";
 import type { ResourceAddress, ResourceState, ResourceType } from "../types/state.ts";
+import { addressKey } from "../types/state.ts";
 import { contentHash as stableContentHash } from "../utils/hash.ts";
 import type { BackendRuntimeInput, ProjectRuntimeContext } from "./project-runtime.ts";
 import { readProjectRuntime, writeProjectRuntime } from "./project-runtime.ts";
 
 export interface ResourceRuntimeOptions extends DestructiveDecisionOptions {
 	provider?: string;
+	scope?: ResourcePlanScope;
 	refresh?: boolean;
 	refreshOnly?: boolean;
 	quiet?: boolean;
 	onFeedback?: RuntimeFeedbackSink;
 }
 
+export interface ResourcePlanScope {
+	roots: ResourceAddress[];
+	includeDependencies?: boolean;
+}
+
 export interface ResourceRefreshResult {
 	removed: ResourceState[];
 	errors: Array<{ resource: ResourceState; error: string }>;
@@ -42,6 +50,7 @@ export interface ResourcePlanResult {
 	refreshResult?: ResourceRefreshResult;
 	targetProviders?: string[];
 	destructiveActions: PlannedAction[];
+	selectedAddresses?: ResourceAddress[];
 }
 
 export type DestructivePolicy = "block" | "prompt" | "force";
@@ -164,11 +173,17 @@ export async function planProjectContext(
 	ctx: ProjectRuntimeContext,
 	options: ResourceRuntimeOptions = {},
 ): Promise<ResourcePlanResult> {
-	const targetProviders = resolveTargetProviders(options.provider);
+	let targetProviders = resolveTargetProviders(options.provider);
+	if (!targetProviders && options.scope) {
+		targetProviders = [...new Set(options.scope.roots.map((root) => root.provider))];
+	}
+	const selectedAddresses = options.scope ? resolvePlanScope(ctx, targetProviders ?? [], options.scope) : undefined;
+	const resourceKeys = selectedAddresses ? new Set(selectedAddresses.map(addressKey)) : undefined;
 	const refreshResult =
 		options.refresh !== false && ctx.state.listResources().length > 0
 			? await refreshState(ctx.state, ctx.providers, {
 					targetProviders,
+					resourceKeys,
 					config: ctx.config,
 					quiet: options.quiet ?? true,
 					onFeedback: options.onFeedback,
@@ -178,6 +193,7 @@ export async function planProjectContext(
 	const plan = await buildPlan(ctx.config, ctx.state.getStateFile(), {
 		providers: targetProviders,
 		configPath: ctx.configPath,
+		resourceAddresses: selectedAddresses,
 	});
 
 	return {
@@ -186,9 +202,34 @@ export async function planProjectContext(
 		refreshResult: toResourceRefreshResult(refreshResult),
 		targetProviders,
 		destructiveActions: selectDestructive(plan.actions),
+		selectedAddresses,
 	};
 }
 
+function resolvePlanScope(
+	ctx: ProjectRuntimeContext,
+	targetProviders: string[],
+	scope: ResourcePlanScope,
+): ResourceAddress[] {
+	if (scope.roots.length === 0) {
+		throw new UserError("Resource plan scope requires at least one root address.");
+	}
+	for (const root of scope.roots) {
+		if (!targetProviders.includes(root.provider)) {
+			throw new UserError(
+				`Scoped resource ${addressKey(root)} is outside the selected provider set: ${targetProviders.join(", ")}.`,
+			);
+		}
+	}
+	const graph = buildDependencyGraph(ctx.config, targetProviders);
+	for (const root of scope.roots) {
+		if (!graph.nodes.has(addressKey(root))) {
+			throw new UserError(`Scoped resource ${addressKey(root)} is not declared in the project config.`);
+		}
+	}
+	return scope.includeDependencies === false ? [...scope.roots] : collectDependencyClosure(graph, scope.roots);
+}
+
 export async function executePlannedProject(
 	planned: ResourcePlanResult,
 	options: DestructiveDecisionOptions & {

packages/sdk/src/internal/graph/dependency.ts

@@ -11,6 +11,24 @@ export interface DependencyGraph {
 	edges: Map<string, Set<string>>;
 }
 
+/** Resolve explicit resource roots plus every declared transitive dependency. */
+export function collectDependencyClosure(graph: DependencyGraph, roots: readonly ResourceAddress[]): ResourceAddress[] {
+	const selected = new Map<string, ResourceAddress>();
+
+	function visit(address: ResourceAddress): void {
+		const key = addressKey(address);
+		if (selected.has(key)) return;
+		selected.set(key, graph.nodes.get(key) ?? address);
+		for (const dependencyKey of graph.edges.get(key) ?? []) {
+			const dependency = graph.nodes.get(dependencyKey);
+			if (dependency) visit(dependency);
+		}
+	}
+
+	for (const root of roots) visit(root);
+	return [...selected.values()];
+}
+
 export function buildDependencyGraph(config: ProjectConfig, targetProviders: string[]): DependencyGraph {
 	const nodes = new Map<string, ResourceAddress>();
 	const edges = new Map<string, Set<string>>();