@better-openclaw/core 1.0.26 → 1.0.30

package/src/composer.ts

@@ -1,26 +1,8 @@
 import { Scalar, stringify } from "yaml";
+import { getFrameworkById } from "./frameworks/index.js";
+import type { AgentFrameworkDefinition, FrameworkComposeOptions } from "./frameworks/types.js";
 import { getDbRequirements } from "./generators/postgres-init.js";
-import type {
-	ComposeOptions,
-	OpenclawImageVariant,
-	ResolverOutput,
-	ServiceCategory,
-} from "./types.js";
-
-/** Maps image variant to the Docker image string. */
-const IMAGE_VARIANTS: Record<OpenclawImageVariant, string> = {
-	official: "ghcr.io/openclaw/openclaw",
-	coolify: "coollabsio/openclaw",
-	alpine: "alpine/openclaw",
-};
-
-/** Returns the OpenClaw image string with version tag for a given variant. */
-function getOpenclawImage(variant: OpenclawImageVariant, version: string): string {
-	const base = IMAGE_VARIANTS[variant];
-	// Coolify and alpine images use :latest by default
-	const tag = variant === "official" ? version : "latest";
-	return `${base}:${tag}`;
-}
+import type { ComposeOptions, ResolverOutput, ServiceCategory } from "./types.js";
 
 /** Creates a YAML scalar that is always quoted — avoids YAML 1.1 bare `no` → false. */
 export function quotedStr(value: string): Scalar {
@@ -55,169 +37,54 @@ const CATEGORY_PROFILE_MAP: Partial<Record<ServiceCategory, { file: string; prof
 
 export const YAML_OPTIONS = { lineWidth: 120, nullStr: "" };
 
-// ── Shared Gateway Builder ──────────────────────────────────────────────────
+// ── Framework-Aware Gateway Builder ─────────────────────────────────────────
+
+import type { GatewayBuildResult } from "./frameworks/types.js";
+
+/** Resolves the active framework and converts ComposeOptions to FrameworkComposeOptions. */
+function resolveFramework(options: ComposeOptions): AgentFrameworkDefinition {
+	const fw = getFrameworkById(options.primaryFramework ?? "openclaw");
+	if (!fw) {
+		// Fallback to openclaw if unknown framework
+		const fallback = getFrameworkById("openclaw");
+		if (!fallback) throw new Error("OpenClaw framework not registered");
+		return fallback;
+	}
+	return fw;
+}
 
-interface GatewayBuildResult {
-	gatewayService: Record<string, unknown>;
-	cliService: Record<string, unknown>;
-	allVolumes: Set<string>;
+function toFrameworkComposeOptions(options: ComposeOptions): FrameworkComposeOptions {
+	return {
+		projectName: options.projectName,
+		proxy: options.proxy,
+		proxyHttpPort: options.proxyHttpPort,
+		proxyHttpsPort: options.proxyHttpsPort,
+		domain: options.domain,
+		gpu: options.gpu,
+		platform: options.platform,
+		deployment: options.deployment ?? "local",
+		frameworkVersion: options.openclawVersion,
+		frameworkImageVariant: options.openclawImage ?? "official",
+		bareMetalNativeHost: options.bareMetalNativeHost,
+		traefikLabels: options.traefikLabels,
+		hardened: options.hardened,
+		frameworkInstallMethod: options.openclawInstallMethod ?? "docker",
+	};
 }
 
 /**
- * Builds the OpenClaw gateway and CLI service entries.
- * Matches the real OpenClaw docker-compose.yml structure:
- * - Bridge port 18790 for ACP/WebSocket
- * - Bind-mount volumes (not named volumes)
- * - Claude web-provider session env vars
- * - Gateway bind mode (--bind lan)
- * - CLI companion service with stdin/tty
+ * Builds gateway and CLI service entries by delegating to the selected framework.
+ * Framework is determined by options.primaryFramework (defaults to "openclaw").
  */
 function buildGatewayServices(
 	resolved: ResolverOutput,
 	options: ComposeOptions,
 	dependsOn?: Record<string, { condition: string }>,
-): GatewayBuildResult {
-	const allVolumes = new Set<string>();
-
-	// Gateway environment
-	const gatewayEnv: Record<string, string> = {
-		HOME: "/home/node",
-		TERM: "xterm-256color",
-		OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}",
-		OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}",
-		// Claude web-provider session vars (optional, user fills in .env)
-		CLAUDE_AI_SESSION_KEY: "${CLAUDE_AI_SESSION_KEY:-}",
-		CLAUDE_WEB_SESSION_KEY: "${CLAUDE_WEB_SESSION_KEY:-}",
-		CLAUDE_WEB_COOKIE: "${CLAUDE_WEB_COOKIE:-}",
-	};
-
-	// Add AI provider API keys to gateway environment
-	const providerKeys = [
-		"OPENAI_API_KEY",
-		"ANTHROPIC_API_KEY",
-		"GOOGLE_API_KEY",
-		"XAI_API_KEY",
-		"DEEPSEEK_API_KEY",
-		"GROQ_API_KEY",
-		"OPENROUTER_API_KEY",
-		"MISTRAL_API_KEY",
-		"TOGETHER_API_KEY",
-		"OLLAMA_API_KEY",
-	];
-	for (const key of providerKeys) {
-		gatewayEnv[key] = `\${${key}}`;
-	}
-
-	// Gateway volumes (bind-mount style matching real docker-setup.sh)
-	const gatewayVolumes: string[] = [
-		"${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw",
-		"${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace",
-	];
-
-	// Collect env vars and volume mounts from companion services
-	for (const { definition: def } of resolved.services) {
-		for (const env of def.openclawEnvVars) {
-			gatewayEnv[env.key] = env.secret ? `\${${env.key}}` : env.defaultValue;
-		}
-		if (def.openclawVolumeMounts) {
-			for (const vol of def.openclawVolumeMounts) {
-				const isBindMount =
-					vol.name.startsWith("./") || vol.name.startsWith("/") || vol.name.startsWith("~");
-				if (!isBindMount) {
-					allVolumes.add(vol.name);
-				}
-				gatewayVolumes.push(`${vol.name}:${vol.containerPath}`);
-			}
-		}
-	}
-
-	// Gateway service
-	const defaultImage = getOpenclawImage(
-		options.openclawImage ?? "official",
-		options.openclawVersion,
-	);
-	const gateway: Record<string, unknown> = {
-		image: `\${OPENCLAW_IMAGE:-${defaultImage}}`,
-		environment: gatewayEnv,
-		volumes: gatewayVolumes,
-		ports: ["${OPENCLAW_GATEWAY_PORT:-18789}:18789", "${OPENCLAW_BRIDGE_PORT:-18790}:18790"],
-		networks: ["openclaw-network"],
-		init: true,
-		restart: "unless-stopped",
-		command: [
-			"node",
-			"dist/index.js",
-			"gateway",
-			"--bind",
-			"${OPENCLAW_GATEWAY_BIND:-lan}",
-			"--port",
-			"18789",
-			"--allow-unconfigured",
-		],
-		healthcheck: {
-			test: [
-				"CMD",
-				"node",
-				"-e",
-				"fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
-			],
-			interval: "30s",
-			timeout: "5s",
-			retries: 5,
-			start_period: "20s",
-		},
-	};
-
-	// Traefik labels for the gateway
-	const gwTraefikLabels = options.traefikLabels?.get("openclaw-gateway");
-	if (gwTraefikLabels) {
-		gateway.labels = gwTraefikLabels;
-	}
-
-	if (options.bareMetalNativeHost) {
-		gateway.extra_hosts = ["host.docker.internal:host-gateway"];
-	}
-
-	if (dependsOn && Object.keys(dependsOn).length > 0) {
-		gateway.depends_on = dependsOn;
-	}
-
-	// CLI companion service (matching real OpenClaw docker-compose.yml)
-	// Build CLI environment with same keys as gateway for consistency
-	const cliEnv: Record<string, string> = {
-		HOME: "/home/node",
-		TERM: "xterm-256color",
-		OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}",
-		OPENCLAW_ALLOW_INSECURE_PRIVATE_WS: "${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}",
-		BROWSER: "echo",
-		CLAUDE_AI_SESSION_KEY: "${CLAUDE_AI_SESSION_KEY:-}",
-		CLAUDE_WEB_SESSION_KEY: "${CLAUDE_WEB_SESSION_KEY:-}",
-		CLAUDE_WEB_COOKIE: "${CLAUDE_WEB_COOKIE:-}",
-	};
-
-	// Add same AI provider API keys to CLI for direct AI interactions
-	for (const key of providerKeys) {
-		cliEnv[key] = `\${${key}}`;
-	}
-
-	const cliService: Record<string, unknown> = {
-		image: `\${OPENCLAW_IMAGE:-${defaultImage}}`,
-		network_mode: "service:openclaw-gateway",
-		cap_drop: ["NET_RAW", "NET_ADMIN"],
-		security_opt: ["no-new-privileges:true"],
-		environment: cliEnv,
-		volumes: [
-			"${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw",
-			"${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace",
-		],
-		stdin_open: true,
-		tty: true,
-		init: true,
-		entrypoint: ["node", "dist/index.js"],
-		depends_on: ["openclaw-gateway"],
-	};
-
-	return { gatewayService: gateway, cliService: cliService, allVolumes };
+): GatewayBuildResult & { framework: AgentFrameworkDefinition } {
+	const framework = resolveFramework(options);
+	const fwOptions = toFrameworkComposeOptions(options);
+	const result = framework.buildGatewayService(resolved, fwOptions, dependsOn);
+	return { ...result, framework };
 }
 
 // ── Shared Companion Service Builder ────────────────────────────────────────
@@ -227,6 +94,7 @@ export function buildCompanionService(
 	resolved: ResolverOutput,
 	options: ComposeOptions,
 	allVolumes: Set<string>,
+	networkName?: string,
 ): { entry: Record<string, unknown>; volumeNames: string[] } {
 	const svc: Record<string, unknown> = {};
 	const volumeNames: string[] = [];
@@ -235,7 +103,8 @@ export function buildCompanionService(
 	if (def.gitSource && def.buildContext) {
 		const subdir = def.gitSource.subdirectory || ".";
 		const ctxPath = def.buildContext.context || ".";
-		const contextFull = subdir === "." ? `./repos/${def.id}/${ctxPath}` : `./repos/${def.id}/${subdir}/${ctxPath}`;
+		const contextFull =
+			subdir === "." ? `./repos/${def.id}/${ctxPath}` : `./repos/${def.id}/${subdir}/${ctxPath}`;
 		const buildBlock: Record<string, unknown> = { context: contextFull };
 		if (def.buildContext.dockerfile) {
 			buildBlock.dockerfile = def.buildContext.dockerfile;
@@ -341,7 +210,11 @@ export function buildCompanionService(
 	}
 
 	svc.restart = def.restartPolicy;
-	svc.networks = def.networks;
+	// Map "openclaw-network" to the active framework's network name at compose-time
+	// so service definitions don't need mass-editing (190+ files).
+	svc.networks = networkName
+		? def.networks.map((n: string) => (n === "openclaw-network" ? networkName : n))
+		: def.networks;
 
 	if (def.command) svc.command = def.command;
 	if (def.entrypoint) svc.entrypoint = def.entrypoint;
@@ -445,7 +318,10 @@ export function buildCompanionService(
  *
  * Returns null when no setup is needed (no PostgreSQL or no DB requirements).
  */
-export function buildPostgresSetup(resolved: ResolverOutput): Record<string, unknown> | null {
+export function buildPostgresSetup(
+	resolved: ResolverOutput,
+	networkName = "openclaw-network",
+): Record<string, unknown> | null {
 	const hasPostgres = resolved.services.some((s) => s.definition.id === "postgresql");
 	if (!hasPostgres) return null;
 
@@ -500,7 +376,7 @@ export function buildPostgresSetup(resolved: ResolverOutput): Record<string, unk
 		entrypoint: ["/bin/sh", "-c"],
 		command: [scriptLines.join("\n")],
 		restart: quotedStr("no"),
-		networks: ["openclaw-network"],
+		networks: [networkName],
 	};
 }
 
@@ -524,6 +400,10 @@ export function compose(resolved: ResolverOutput, options: ComposeOptions): stri
 	const services: Record<string, Record<string, unknown>> = {};
 	let allVolumes = new Set<string>();
 
+	const framework = resolveFramework(options);
+	const gatewayKey = `${framework.id}-gateway`;
+	const cliKey = `${framework.id}-cli`;
+
 	if (!isDirectInstall) {
 		const {
 			gatewayService,
@@ -531,14 +411,20 @@ export function compose(resolved: ResolverOutput, options: ComposeOptions): stri
 			allVolumes: gwVolumes,
 		} = buildGatewayServices(resolved, options, gatewayDependsOn);
 		allVolumes = gwVolumes;
-		services["openclaw-gateway"] = gatewayService;
+		services[gatewayKey] = gatewayService;
 		// CLI service added after companions
 		// Determine which services need DB setup so we can redirect their depends_on
 		const dbReqs = getDbRequirements(resolved);
 		const dbServiceIds = new Set(dbReqs.map((r) => r.serviceId));
 
 		for (const { definition: def } of resolved.services) {
-			const { entry } = buildCompanionService(def, resolved, options, allVolumes);
+			const { entry } = buildCompanionService(
+				def,
+				resolved,
+				options,
+				allVolumes,
+				framework.networkName,
+			);
 			if (dbServiceIds.has(def.id) && entry.depends_on) {
 				const deps = entry.depends_on as Record<string, { condition: string }>;
 				if (deps.postgresql) {
@@ -549,19 +435,46 @@ export function compose(resolved: ResolverOutput, options: ComposeOptions): stri
 			services[def.id] = entry;
 		}
 
-		const pgSetup = buildPostgresSetup(resolved);
+		const pgSetup = buildPostgresSetup(resolved, framework.networkName);
 		if (pgSetup) {
 			services["postgres-setup"] = pgSetup;
 		}
 
-		services["openclaw-cli"] = cliService;
+		// Add companion framework containers
+		if (options.companionFrameworks && options.companionFrameworks.length > 0) {
+			const fwOptions = toFrameworkComposeOptions(options);
+			for (const companionId of options.companionFrameworks) {
+				const companionFw = getFrameworkById(companionId);
+				if (!companionFw || companionFw.id === framework.id) continue;
+				if (companionFw.buildCompanionService) {
+					const companionEntry = companionFw.buildCompanionService(resolved, fwOptions);
+					if (companionEntry) {
+						services[`${companionFw.id}-companion`] = companionEntry;
+					}
+				} else {
+					// Fallback: build a gateway-style container for the companion
+					const companionResult = companionFw.buildGatewayService(resolved, fwOptions);
+					services[`${companionFw.id}-companion`] = companionResult.gatewayService;
+				}
+			}
+		}
+
+		if (cliService) {
+			services[cliKey] = cliService;
+		}
 	} else {
 		// Direct install: no gateway/CLI containers, just companion services
 		const dbReqs = getDbRequirements(resolved);
 		const dbServiceIds = new Set(dbReqs.map((r) => r.serviceId));
 
 		for (const { definition: def } of resolved.services) {
-			const { entry } = buildCompanionService(def, resolved, options, allVolumes);
+			const { entry } = buildCompanionService(
+				def,
+				resolved,
+				options,
+				allVolumes,
+				framework.networkName,
+			);
 			if (dbServiceIds.has(def.id) && entry.depends_on) {
 				const deps = entry.depends_on as Record<string, { condition: string }>;
 				if (deps.postgresql) {
@@ -572,7 +485,7 @@ export function compose(resolved: ResolverOutput, options: ComposeOptions): stri
 			services[def.id] = entry;
 		}
 
-		const pgSetup = buildPostgresSetup(resolved);
+		const pgSetup = buildPostgresSetup(resolved, framework.networkName);
 		if (pgSetup) {
 			services["postgres-setup"] = pgSetup;
 		}
@@ -583,7 +496,7 @@ export function compose(resolved: ResolverOutput, options: ComposeOptions): stri
 		volumes[v] = null;
 	}
 
-	const networks = { "openclaw-network": { driver: "bridge" } };
+	const networks = { [framework.networkName]: { driver: "bridge" } };
 
 	return stringify({ services, volumes, networks }, YAML_OPTIONS);
 }
@@ -604,6 +517,7 @@ interface ServiceInfo {
 export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptions): ComposeResult {
 	const isDirectInstall = options.openclawInstallMethod === "direct";
 	const allVolumes = new Set<string>();
+	const framework = resolveFramework(options);
 
 	// Build all companion service entries & classify by category
 	const serviceInfos: ServiceInfo[] = [];
@@ -611,7 +525,13 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 	const dbServiceIds = new Set(dbReqs.map((r) => r.serviceId));
 
 	for (const { definition: def } of resolved.services) {
-		const { entry, volumeNames } = buildCompanionService(def, resolved, options, allVolumes);
+		const { entry, volumeNames } = buildCompanionService(
+			def,
+			resolved,
+			options,
+			allVolumes,
+			framework.networkName,
+		);
 		// Redirect DB-dependent services to depend on postgres-setup
 		if (dbServiceIds.has(def.id) && entry.depends_on) {
 			const deps = entry.depends_on as Record<string, { condition: string }>;
@@ -633,12 +553,13 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 			if (!profileFileMap[mapping.file]) {
 				profileFileMap[mapping.file] = { profile: mapping.profile, services: [] };
 			}
-			profileFileMap[mapping.file]!.services.push(info);
+			profileFileMap[mapping.file]?.services.push(info);
 		} else {
 			baseServiceIds.add(info.id);
 		}
 	}
-
+	const gatewayKey = `${framework.id}-gateway`;
+	const cliKey = `${framework.id}-cli`;
 	const baseServices: Record<string, Record<string, unknown>> = {};
 
 	if (!isDirectInstall) {
@@ -661,7 +582,7 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 		// Merge gateway volumes into allVolumes
 		for (const v of gwVolumes) allVolumes.add(v);
 
-		baseServices["openclaw-gateway"] = gatewayService;
+		baseServices[gatewayKey] = gatewayService;
 
 		for (const info of serviceInfos) {
 			if (baseServiceIds.has(info.id)) {
@@ -670,12 +591,32 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 		}
 
 		// Add postgres-setup init container if needed
-		const pgSetup = buildPostgresSetup(resolved);
+		const pgSetup = buildPostgresSetup(resolved, framework.networkName);
 		if (pgSetup) {
 			baseServices["postgres-setup"] = pgSetup;
 		}
 
-		baseServices["openclaw-cli"] = cliService;
+		// Add companion framework containers
+		if (options.companionFrameworks && options.companionFrameworks.length > 0) {
+			const fwOptions = toFrameworkComposeOptions(options);
+			for (const companionId of options.companionFrameworks) {
+				const companionFw = getFrameworkById(companionId);
+				if (!companionFw || companionFw.id === framework.id) continue;
+				if (companionFw.buildCompanionService) {
+					const companionEntry = companionFw.buildCompanionService(resolved, fwOptions);
+					if (companionEntry) {
+						baseServices[`${companionFw.id}-companion`] = companionEntry;
+					}
+				} else {
+					const companionResult = companionFw.buildGatewayService(resolved, fwOptions);
+					baseServices[`${companionFw.id}-companion`] = companionResult.gatewayService;
+				}
+			}
+		}
+
+		if (cliService) {
+			baseServices[cliKey] = cliService;
+		}
 	} else {
 		// Direct install: no gateway/CLI containers
 		for (const info of serviceInfos) {
@@ -684,7 +625,7 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 			}
 		}
 
-		const pgSetup = buildPostgresSetup(resolved);
+		const pgSetup = buildPostgresSetup(resolved, framework.networkName);
 		if (pgSetup) {
 			baseServices["postgres-setup"] = pgSetup;
 		}
@@ -695,7 +636,7 @@ export function composeMultiFile(resolved: ResolverOutput, options: ComposeOptio
 		sortedAllVolumes[v] = null;
 	}
 
-	const networks = { "openclaw-network": { driver: "bridge" } };
+	const networks = { [framework.networkName]: { driver: "bridge" } };
 
 	const files: Record<string, string> = {};
 	files["docker-compose.yml"] = stringify(

package/src/deployers/coolify.ts

@@ -151,6 +151,11 @@ export class CoolifyDeployer implements PaasDeployer {
 	}
 
 	async deploy(input: DeployInput): Promise<DeployResult> {
+		input.logger?.info("deployment", `Starting deployment to Coolify`, {
+			projectName: input.projectName,
+			instanceUrl: input.target.instanceUrl,
+		});
+
 		const step1: DeployStep = { step: "Discover server", status: "pending" };
 		const step2: DeployStep = {
 			step: "Find or create project",
@@ -318,6 +323,29 @@ export class CoolifyDeployer implements PaasDeployer {
 
 			result.dashboardUrl = `${base}/project/${project.uuid}`;
 
+			input.logger?.log({
+				level: "info",
+				category: "deployment",
+				message: `Deployment to Coolify succeeded`,
+				outcome: "success",
+				context: {
+					projectId: project.uuid,
+					serviceId: service.uuid,
+					dashboardUrl: result.dashboardUrl,
+				},
+				steps: steps.map((s) => ({
+					name: s.step,
+					status:
+						s.status === "done"
+							? ("success" as const)
+							: s.status === "error"
+								? ("failure" as const)
+								: ("in_progress" as const),
+					detail: s.detail,
+					startedAt: new Date().toISOString(),
+				})),
+			});
+
 			return result;
 		} catch (err) {
 			const running = steps.find((s) => s.status === "running");
@@ -329,6 +357,16 @@ export class CoolifyDeployer implements PaasDeployer {
 
 			result.error = err instanceof Error ? err.message : String(err);
 
+			input.logger?.error(
+				"deployment",
+				`Deployment to Coolify failed`,
+				err instanceof Error ? err : null,
+				{
+					projectName: input.projectName,
+					failedStep: running?.step,
+				},
+			);
+
 			return result;
 		}
 	}

package/src/deployers/dokploy.ts

@@ -139,6 +139,11 @@ export class DokployDeployer implements PaasDeployer {
 	}
 
 	async deploy(input: DeployInput): Promise<DeployResult> {
+		input.logger?.info("deployment", `Starting deployment to Dokploy`, {
+			projectName: input.projectName,
+			instanceUrl: input.target.instanceUrl,
+		});
+
 		const step1: DeployStep = {
 			step: "Find or create project",
 			status: "pending",
@@ -309,6 +314,29 @@ export class DokployDeployer implements PaasDeployer {
 
 			result.dashboardUrl = `${base}/dashboard/project/${project.projectId}/environment/${env.environmentId}/services/compose/${stack?.composeId}?tab=deployments`;
 
+			input.logger?.log({
+				level: "info",
+				category: "deployment",
+				message: `Deployment to Dokploy succeeded`,
+				outcome: "success",
+				context: {
+					projectId: project.projectId,
+					composeId: stack?.composeId,
+					dashboardUrl: result.dashboardUrl,
+				},
+				steps: steps.map((s) => ({
+					name: s.step,
+					status:
+						s.status === "done"
+							? ("success" as const)
+							: s.status === "error"
+								? ("failure" as const)
+								: ("in_progress" as const),
+					detail: s.detail,
+					startedAt: new Date().toISOString(),
+				})),
+			});
+
 			return result;
 		} catch (err) {
 			const running = steps.find((s) => s.status === "running");
@@ -321,6 +349,16 @@ export class DokployDeployer implements PaasDeployer {
 
 			result.error = err instanceof Error ? err.message : String(err);
 
+			input.logger?.error(
+				"deployment",
+				`Deployment to Dokploy failed`,
+				err instanceof Error ? err : null,
+				{
+					projectName: input.projectName,
+					failedStep: running?.step,
+				},
+			);
+
 			return result;
 		}
 	}

package/src/deployers/types.ts

@@ -35,6 +35,8 @@ export interface DeployInput {
 	description?: string;
 	/** Optional server ID to deploy to (for PaaS platforms managing multiple servers) */
 	serverId?: string;
+	/** Optional operations logger for persistent audit logging */
+	logger?: import("../logger/logger.js").OperationsLogger;
 }
 
 /** Step-level status for deploy progress. */