fix(bailian): harden native deployment lifecycle

Author: chenanran555

examples/bailian/deployment/agents.yaml

@@ -55,4 +55,4 @@ deployments:
       # Local file uploaded at `apply` time and mounted into each run's Session.
       - type: file
         source: ./data/report-template.md
-        mount_path: /data/report-template.md
+        mount_path: /mnt/report-template.md

packages/sdk/src/internal/core/validate-config.ts

@@ -9,7 +9,7 @@ import { getProvider } from "../providers/registry.ts";
 import type { ProjectConfig } from "../types/config.ts";
 import type { Diagnostic } from "../types/plan.ts";
 import type { ResourceAddress } from "../types/state.ts";
-import { providerMountPrefix } from "../utils/sandbox-mount.ts";
+import { providerMountPrefix, resolveSandboxMountPath } from "../utils/sandbox-mount.ts";
 import { findMissingBailianMcpToolConfigs } from "../validation/bailian.ts";
 
 export interface ValidateProjectConfigOptions {
@@ -370,7 +370,11 @@ export function collectProviderCapabilities(
 			// resources accept files only. Surface what gets dropped.
 			for (const [name, deployment] of Object.entries(config.deployments ?? {})) {
 				if (deployment.provider && deployment.provider !== providerName) continue;
-				const addr: ResourceAddress = { type: "deployment", name, provider: providerName };
+				const addr: ResourceAddress = {
+					type: "deployment",
+					name,
+					provider: providerName,
+				};
 
 				if (deployment.initial_events?.some((event) => event.type === "user.define_outcome")) {
 					diagnostics.warning(
@@ -379,6 +383,15 @@ export function collectProviderCapabilities(
 						addr,
 					);
 				}
+				if (
+					!deployment.initial_events?.some((event) => event.type === "user.message" || event.type === "system.message")
+				) {
+					diagnostics.error(
+						`${providerName}.deployment.initial_events.message_required`,
+						`deployment.${name}: Bailian requires at least one user.message or system.message initial event; user.define_outcome events are dropped.`,
+						addr,
+					);
+				}
 
 				if (deployment.resources?.some((resource) => resource.type === "github_repository")) {
 					diagnostics.warning(
@@ -387,6 +400,44 @@ export function collectProviderCapabilities(
 						addr,
 					);
 				}
+
+				const mountPrefix = providerMountPrefix(providerName);
+				const normalizedMountPaths = new Set<string>();
+				for (const resource of deployment.resources ?? []) {
+					if (resource.type !== "file") continue;
+					if (!resource.mount_path?.trim()) {
+						diagnostics.error(
+							`${providerName}.deployment.file.mount_path.required`,
+							`deployment.${name}: Bailian file resources require mount_path.`,
+							addr,
+						);
+						continue;
+					}
+					if (
+						mountPrefix &&
+						resource.mount_path.startsWith("/") &&
+						resource.mount_path !== mountPrefix &&
+						!resource.mount_path.startsWith(`${mountPrefix}/`)
+					) {
+						diagnostics.error(
+							`${providerName}.deployment.file.mount_path.invalid`,
+							`deployment.${name}: Bailian file mount_path must start with '${mountPrefix}/'.`,
+							addr,
+						);
+						continue;
+					}
+
+					const normalizedMountPath = resolveSandboxMountPath(providerName, resource.mount_path);
+					if (normalizedMountPaths.has(normalizedMountPath)) {
+						diagnostics.error(
+							`${providerName}.deployment.file.mount_path.duplicate`,
+							`deployment.${name}: Bailian file mount_path '${normalizedMountPath}' is duplicated after normalization.`,
+							addr,
+						);
+					} else {
+						normalizedMountPaths.add(normalizedMountPath);
+					}
+				}
 			}
 		}
 
@@ -477,7 +528,11 @@ export function collectProviderCapabilities(
 		if (config.deployments && caps.deployment.tier === "emulated") {
 			for (const [name, dep] of Object.entries(config.deployments)) {
 				if (dep.provider && dep.provider !== providerName) continue;
-				const addr: ResourceAddress = { type: "deployment", name, provider: providerName };
+				const addr: ResourceAddress = {
+					type: "deployment",
+					name,
+					provider: providerName,
+				};
 
 				if (dep.schedule) {
 					diagnostics.warning(

packages/sdk/src/internal/executor/executor.ts

@@ -5,6 +5,7 @@ import { getResourceDeclaration } from "../planner/declaration.ts";
 import { computeReplacementFingerprint, computeResourceHash } from "../planner/hasher.ts";
 import { buildReadinessBaseline } from "../planner/plan-semantics.ts";
 import { ApiError, ConflictError } from "../providers/base-client.ts";
+import { DeploymentCreateConflictError } from "../providers/deployment-conflict.ts";
 import { readComparableIfSupported } from "../providers/drift-support.ts";
 import type { RemoteResource } from "../providers/interface.ts";
 import type { DriftReadAdapter, ResourceCrudAdapter } from "../providers/resource-workflow.ts";
@@ -597,16 +598,41 @@ async function executeActionInner(
 		case "deployment": {
 			const decl = ctx.config.deployments![name]!;
 			const refs = resolveDeploymentRefs(name, ctx.config, address.provider, ctx.state);
-			if (isUpdate) {
-				result = await provider.updateDeployment(existingId!, name, decl, refs, ctx.configPath ?? "");
-			} else {
+			const hasLocalFileSources = decl.resources?.some(
+				(resource) => resource.type === "file" && !resource.file_id && Boolean(resource.source),
+			);
+			const materializeDeployment = async (): Promise<RemoteResource> => {
 				try {
-					result = await provider.createDeployment(name, decl, refs, ctx.configPath ?? "");
+					return await provider.createDeployment(name, decl, refs, ctx.configPath ?? "");
 				} catch (err) {
-					result = await adoptOnConflict(err, address, provider, ctx.onFeedback, {
-						onExisting: (existing) => provider.updateDeployment(existing.id!, name, decl, refs, ctx.configPath ?? ""),
+					const preparedFiles = err instanceof DeploymentCreateConflictError ? err.preparedFiles : undefined;
+					const existing = await adoptOnConflict(err, address, provider, ctx.onFeedback, {
+						onExisting: (existing) =>
+							provider.updateDeployment(existing.id!, name, decl, refs, ctx.configPath ?? "", preparedFiles),
+					});
+					adopted = true;
+					return existing;
+				}
+			};
+			if (isUpdate && existingId) {
+				result = await provider.updateDeployment(existingId, name, decl, refs, ctx.configPath ?? "");
+			} else {
+				// A deployment with local file sources uploads before its create request. If the
+				// remote deployment already exists, an optimistic create would upload once,
+				// conflict, then upload again during adoption. Preflight this side-effecting
+				// path so the existing deployment is updated with a single set of uploads.
+				const existing = hasLocalFileSources ? await findExistingByNames(provider, "deployment", [name]) : null;
+				if (existing) {
+					result = await provider.updateDeployment(existing.resource.id!, name, decl, refs, ctx.configPath ?? "");
+					emitRuntimeFeedback(ctx.onFeedback, {
+						type: "resource_adopted",
+						level: "info",
+						resource: address,
+						message: `adopt deployment.${name} (${address.provider}) — already existed remotely as "${existing.name}"`,
 					});
 					adopted = true;
+				} else {
+					result = await materializeDeployment();
 				}
 			}
 			break;

packages/sdk/src/internal/planner/hasher.ts

@@ -28,9 +28,16 @@ export async function computeResourceHash(
 		}
 	}
 
+	if (address.type === "file" && basePath) {
+		const fileDecl = decl as { source: string };
+		const fileHash = computeLocalFileContentHash(fileDecl.source, basePath);
+		return contentHash({ decl, fileHash });
+	}
+
 	if (address.type === "deployment") {
 		const refs = resolveDeploymentReferenceIds(decl as DeploymentRefDecl, config, address.provider, state);
-		if (refs) return contentHash({ decl, refs });
+		const sourceHashes = basePath ? computeDeploymentSourceHashes(decl as DeploymentRefDecl, basePath) : undefined;
+		if (refs || sourceHashes) return contentHash({ decl, refs, sourceHashes });
 	}
 
 	if (address.type === "template") {
@@ -77,6 +84,7 @@ function resolveChannelReferenceIds(
 interface DeploymentRefDecl {
 	agent: string;
 	environment?: string;
+	resources?: Array<{ type: string; file_id?: string; source?: string }>;
 }
 
 interface TemplateRefDecl {
@@ -150,6 +158,26 @@ function getDeclaration(address: ResourceAddress, config: ProjectConfig): unknow
 	return getResourceDeclaration(address, config);
 }
 
+function computeDeploymentSourceHashes(decl: DeploymentRefDecl, basePath: string): Record<string, string> | undefined {
+	const sources = [
+		...new Set(
+			(decl.resources ?? []).flatMap((resource) =>
+				resource.type === "file" && !resource.file_id && resource.source ? [resource.source] : [],
+			),
+		),
+	];
+	if (sources.length === 0) return undefined;
+
+	return Object.fromEntries(sources.map((source) => [source, computeLocalFileContentHash(source, basePath)]));
+}
+
+export function computeLocalFileContentHash(source: string, basePath: string): string {
+	const fullPath = resolve(dirname(basePath), source);
+	const stat = statSync(fullPath, { throwIfNoEntry: false });
+	if (!stat?.isFile()) return "";
+	return contentHash(readFileSync(fullPath).toString("base64"));
+}
+
 export function computeSkillContentHash(source: string, basePath: string): string {
 	const fullPath = resolve(dirname(basePath), source);
 	const stat = statSync(fullPath, { throwIfNoEntry: false });

packages/sdk/src/internal/planner/planner.ts

@@ -5,6 +5,7 @@ import {
 } from "../core/validate-config.ts";
 import { DiagnosticCollector } from "../diagnostics/diagnostics.ts";
 import { buildDependencyGraph, type DependencyGraph, topologicalSort } from "../graph/dependency.ts";
+import { getProvider } from "../providers/registry.ts";
 import type { ProjectConfig } from "../types/config.ts";
 import type { ExecutionPlan, PlannedAction } from "../types/plan.ts";
 import type { ResourceAddress, StateFile } from "../types/state.ts";
@@ -53,6 +54,10 @@ export async function buildPlan(
 		const desiredHash = await computeResourceHash(address, config, options.configPath, hashStateLookup);
 		const existing = stateIndex.get(key);
 		const deps = getDependencies(address, graph);
+		const needsNativeDeploymentMaterialization =
+			address.type === "deployment" &&
+			existing?.remote_id === null &&
+			getProvider(address.provider)?.capabilities.deployment.tier === "native";
 
 		if (address.type === "environment" && existing) {
 			const envDecl = config.environments?.[address.name];
@@ -134,6 +139,17 @@ export async function buildPlan(
 				after: { content_hash: desiredHash },
 				dependencies: deps,
 			});
+		} else if (needsNativeDeploymentMaterialization) {
+			actions.push({
+				action: "update",
+				address,
+				driftKind: "none",
+				readinessImpact: "blocking",
+				reason: "Materialize legacy state as a native deployment",
+				before: { content_hash: existing.desired_hash ?? existing.content_hash },
+				after: { content_hash: desiredHash },
+				dependencies: deps,
+			});
 		} else if (
 			(existing.desired_hash ?? existing.content_hash) !== desiredHash &&
 			existing.drift_status === "drifted"

packages/sdk/src/internal/providers/bailian/adapter.ts

@@ -34,6 +34,7 @@ import type { ProviderSkillInfo } from "../../types/skill-info.ts";
 import type { ResourceType } from "../../types/state.ts";
 import { compactDeep, stripAgentsMetadata } from "../../utils/comparable.ts";
 import { toRemoteResource } from "../base-client.ts";
+import { preserveDeploymentFilesOnConflict } from "../deployment-conflict.ts";
 import type {
 	ComparableRemoteResource,
 	DeploymentContext,
@@ -562,8 +563,12 @@ export class BailianAdapter implements ProviderAdapter {
 	): Promise<RemoteResource> {
 		const uploaded = await this.uploadDeploymentFiles(decl, basePath);
 		const body = mapDeployment(name, decl, refs, this.projectName, uploaded);
-		const res = (await this.client.post("/deployments", body)) as Record<string, unknown>;
-		return toRemoteResource(res);
+		try {
+			const res = (await this.client.post("/deployments", body)) as Record<string, unknown>;
+			return toRemoteResource(res);
+		} catch (error) {
+			preserveDeploymentFilesOnConflict(error, uploaded);
+		}
 	}
 
 	async updateDeployment(
@@ -572,19 +577,15 @@ export class BailianAdapter implements ProviderAdapter {
 		decl: DeploymentDecl,
 		refs: ResolvedDeploymentRefs,
 		basePath: string,
+		preparedFiles?: ReadonlyMap<string, string>,
 	): Promise<RemoteResource> {
 		// Deployments used to be emulated here, so state rows written before native
 		// support carry `remote_id: null`. An update against one has nothing to PATCH —
 		// materialize it remotely instead of failing on an empty path segment.
 		if (!id) return this.createDeployment(name, decl, refs, basePath);
 
-		const uploaded = await this.uploadDeploymentFiles(decl, basePath);
 		const current = (await this.client.get(`/deployments/${id}`)) as Record<string, unknown>;
-		if (current.schedule && !decl.schedule) {
-			throw new UserError(
-				`Deployment '${name}' cannot remove its schedule through the documented Bailian update API; archive and recreate it as a manual deployment.`,
-			);
-		}
+		const uploaded = preparedFiles ? new Map(preparedFiles) : await this.uploadDeploymentFiles(decl, basePath);
 		const body = mapDeploymentUpdate(
 			name,
 			decl,
@@ -815,7 +816,10 @@ function toDeploymentInfo(res: Record<string, unknown>): DeploymentInfo {
 		status: (res.status as string) ?? "unknown",
 		paused_reason: (res.paused_reason as DeploymentInfo["paused_reason"] | null | undefined) ?? undefined,
 		schedule: schedule
-			? { expression: schedule.expression as string, timezone: schedule.timezone as string | undefined }
+			? {
+					expression: schedule.expression as string,
+					timezone: schedule.timezone as string | undefined,
+				}
 			: undefined,
 		attributes: res,
 	};

packages/sdk/src/internal/providers/bailian/mapper.ts

@@ -162,7 +162,10 @@ export function agentToDecl(raw: Record<string, unknown>): Record<string, unknow
 	if (tools?.length) {
 		const toolset = tools.find((t) => t.type === "builtin_toolkit");
 		if (toolset) {
-			const configs = (toolset.configs ?? []) as Array<{ name: string; enabled?: boolean }>;
+			const configs = (toolset.configs ?? []) as Array<{
+				name: string;
+				enabled?: boolean;
+			}>;
 			builtinTools = configs.filter((c) => c.enabled !== false).map((c) => c.name);
 		}
 	}
@@ -236,7 +239,9 @@ export function mapAgent(
 	// Tools: builtin_toolkit + mcp_toolkit blocks
 	const BAILIAN_BUILTINS = new Set(["bash", "read", "write", "edit", "glob", "grep", "download_file"]);
 	if (decl.tools) {
-		const toolConfigs = resolveBuiltinTools(decl.tools, { supportedWireNames: BAILIAN_BUILTINS }).map((tool) => ({
+		const toolConfigs = resolveBuiltinTools(decl.tools, {
+			supportedWireNames: BAILIAN_BUILTINS,
+		}).map((tool) => ({
 			name: tool.wireName,
 			enabled: true,
 		}));
@@ -368,8 +373,7 @@ export function mapDeployment(
 /**
  * Update replaces only the fields present in the payload, so every optional field a
  * deployment can drop locally must be sent explicitly to be cleared remotely.
- * `schedule` is the exception — it has no documented null form, so removing one is
- * rejected in the adapter instead of silently persisting the old cron.
+ * In particular, `schedule: null` switches a scheduled deployment back to manual.
  */
 export function mapDeploymentUpdate(
 	name: string,
@@ -383,6 +387,7 @@ export function mapDeploymentUpdate(
 	body.description = decl.description ?? "";
 	body.vault_ids = refs.vault_ids;
 	body.resources = mapDeploymentResources(decl, uploadedFiles);
+	if (!decl.schedule) body.schedule = null;
 	if (!projectName && !decl.metadata && existingMetadata) body.metadata = existingMetadata;
 	return body;
 }
@@ -396,7 +401,7 @@ function mapDeploymentResources(decl: DeploymentDecl, uploadedFiles?: Map<string
 		const fileId = resource.file_id ?? (resource.source ? uploadedFiles?.get(resource.source) : undefined);
 		if (!fileId) continue;
 		const entry: Record<string, unknown> = { type: "file", file_id: fileId };
-		if (resource.mount_path) entry.mount_path = resource.mount_path;
+		if (resource.mount_path) entry.mount_path = resolveSandboxMountPath("bailian", resource.mount_path);
 		resources.push(entry);
 	}
 	return resources;

packages/sdk/src/internal/providers/claude/adapter.ts

@@ -32,6 +32,7 @@ import type { ResourceType } from "../../types/state.ts";
 import { extractSkillZipFiles } from "../../utils/normalize-skill-zip.ts";
 import { skillNameFromFiles } from "../../utils/skill-manifest.ts";
 import { toRemoteResource } from "../base-client.ts";
+import { preserveDeploymentFilesOnConflict } from "../deployment-conflict.ts";
 import type {
 	DeploymentContext,
 	DeploymentInfo,
@@ -368,8 +369,12 @@ export class ClaudeAdapter implements ProviderAdapter {
 	): Promise<RemoteResource> {
 		const uploaded = await this.uploadDeploymentFiles(decl, basePath);
 		const body = mapDeployment(name, decl, refs, this.projectName, uploaded);
-		const res = (await this.client.post("/deployments", body)) as Record<string, unknown>;
-		return toRemoteResource(res);
+		try {
+			const res = (await this.client.post("/deployments", body)) as Record<string, unknown>;
+			return toRemoteResource(res);
+		} catch (error) {
+			preserveDeploymentFilesOnConflict(error, uploaded);
+		}
 	}
 
 	async updateDeployment(
@@ -378,8 +383,9 @@ export class ClaudeAdapter implements ProviderAdapter {
 		decl: DeploymentDecl,
 		refs: ResolvedDeploymentRefs,
 		basePath: string,
+		preparedFiles?: ReadonlyMap<string, string>,
 	): Promise<RemoteResource> {
-		const uploaded = await this.uploadDeploymentFiles(decl, basePath);
+		const uploaded = preparedFiles ? new Map(preparedFiles) : await this.uploadDeploymentFiles(decl, basePath);
 		const current = (await this.client.get(`/deployments/${id}`)) as Record<string, unknown>;
 		if (current.schedule && !decl.schedule) {
 			throw new UserError(